Date: Tue, 27 May 2008 14:57:09 -0400
From: Andy Lee <[EMAIL PROTECTED]>
Also, when we *do* ask to see people's code (which also happens), it's
not because the code is the best way to express their intentions.
It's because their code is not *fulfilling* their intentions. Not at
all the same as code snippets in documentation.
Au contraire!
You are making the incorrect assumption that the documentation does a
100% correct job of conveying intentions to every person who may read
it.
Even if the doc writer is _perfect_, there is no possible way for
them to write a single, simple discussion of some class member that
conveys to every reader exactly all of the information they need to
know. There are just too many different ways that individual people
interpret language. And present company excluded, just how many
_perfect_ doc writers do you know of?
This is exactly why code samples are so useful in so many
situations. It's not just limited to the scenario you describe.
As far as that specific scenario goes, your description is even
incomplete there. When trying to help someone or explain a concept
to them -- especially when they already have some very specific
intention in mind that's just not being supported by the language or
framework in which they are working -- I have reasonably often asked
them to not necessarily write correct code, but to write code that
would be correct if they could do exactly what they're asking about.
Even if the language doesn't support that specific syntax, having the
intention expressed in code is often still more communicative than
trying to describe it in English.
And yes, in those situations, the response is generally more along
the lines of "well, you can't do that, but here's the more idiomatic
way to do it in <name your language/framework>". But the starting
point is code, because human language does such a poor job of
unambiguously describing algorithms or intentions.
Pete
_______________________________________________
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
