On May 21, 2008, at 11:35 AM, Johnny Lundy wrote:
Seriously, read that assuming you wanted to try out the NSArray
class and tell me how it accomplishes its purpose of documenting
what it is intended to document. It doesn't. And this pattern is
repeated over and over in just about every one of the "Class
References."
All it would take is a single sentence under the "Class Methods"
header, to say that these methods autorelease the returned object
(AND that such autoreleasing means that the object will be
deallocated if the method in which it was created returns). That is
boilerplate, and would have to be copied to all 250 Class Reference
pages, but hey, they copy and paste a lot less important boilerplate
than that.
It would take a lot more than a single sentence to capture all of the
standard patterns that are followed by each class and each method
across all of the API. For example, following from documenting the
pervasive everything-is-autoreleased-unless-created-by-new/copy/alloc
pattern, you would need to explicitly document new/copy/alloc as
returning retain'd instances. And then you would also probably want
to document such things as pervasive use of KVC / KVO. And class
clusters; probably need the details of that, too.
Pretty soon, the documentation is going to be 80% repetition and 20%
actual unique-to-the-class content.
I have taught/mentored/managed/reviewed/interviewed literally hundreds
of Cocoa programmers over the past two decades (counting Cocoa's NeXT
produced predecessors). My experience has been that the most
successful Cocoa programmers are the ones that learn the standard
patterns of the frameworks. They not only learn said patterns, they
write their own code with the same pattern.
I understand the frustration initially experienced by reading, say,
the docs to NSArray and not having every last detail spelled out. At
the same time, most of the details are not NSArray specific and the
sooner the programmer learns that, the more productive they will be!
If anything, "Cocoa Fundamentals Guide" should be added to the long
list of "Companion Guides" that appears at the top of every single
class reference document.
b.bum
_______________________________________________
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]
