434457 (10) [Avatar] Offline
#1
Hi there,

Long time fan, first time poster here.

In the third paragraph of p2, I initially glossed over this sentence and had to re-read it as it was a bit too 'compressed' for lack of a better word. It describes a lot, and to the casual reader it may not be fully understood on first read. I know there are examples explaining this just after this sentence but I like to fully understand a sentence without having to think too much about what it is saying and giving pause for thought.

The sentence is:

Properties allow us to differentiate between the API a type exposes to allow users to access and manipulate its state, and the implementation detail around how that state is maintained.


This is a succinct sentence but IMHO fails to fully engage and describe to the user as to what the difference of properties are from non-property public interfaces.

A suggested re-wording could be something along the lines of:

Properties have the advantage over non-properties (such as fields, methods, etc.) of specifying the interface that a type (class/struct, etc.) exposes to allow users to access and manipulate its state. It allows more fine-grained control of access over merely specifying the implementation detail around how that state is maintained.


I know it's a bit 'dumbed-down' but might allow a more casual (less experienced?) reader a greater understanding of what is being presented.

Just my opinion.

Cheers,
Will
jon.skeet (479) [Avatar] Offline
#2
(Sorry for not replying to this before - I was tracking it, but hadn't remembered to reply.)

I've actually reworded the sentence slightly differently, but hopefully you'll still like it:

"Properties allow us to differentiate between how state access and manipulation is exposed in the API, and how that state is implemented."
434457 (10) [Avatar] Offline
#3
All good, and thanks for the reply. Yep, that's much better.