On May 22, 2008, at 12:25 PM, glenn andreas wrote:
On May 22, 2008, at 10:43 AM, Greg Titus wrote:
A lot of people have already mentioned that the memory management
semantics for these methods are the same everywhere and are
described in the conceptual documentation. I'd like to answer the
obvious follow up question: even if it is described in the concept
docs, how would it hurt to repeat it in the NSArray class method
references? It is just one more line...
But it's not just one more line - it's like a dozen or so (to handle
the whole semantics of the memory management, not to mention the
whole GC vs no GC), and it would be the same dozen lines in hundreds
of different methods.
I don't think you need to cover that much information. I think a
single sentence would suffice to remind people who are generally aware
of the memory management issues, but haven't quite internalized all
the rules yet. And people who aren't aware of those issues would see
there's *something* they need to figure out.
One sentence copied in a few hundred methods is trivial in the grand
scheme of Cocoa documentation. Look at all the lines telling us which
version of OS X each method was available in. Or the "See also" links
(do we really need to be reminded of the -bounds method in the -
setBounds: docs?). Or the fact that all method names are displayed
twice -- once with arguments and once without.
Even if you tried to shorten it up, say, to just make sure that it
"returns an autoreleased object" that would still require the reader
to understand what that means (so if you can shorten it up to just
that, why do you need it there at all? Alternately, if you need to
explain that the object is autoreleased, why don't you have to
explain what that means?).
<sidenote-and-question>
I read a story once about a city that had a tunnel that ran under a
mountain. I wish I could remember the exact story and what book I
read it in. The gist of it was that the engineers needed to figure
out how to word a sign at the end of the tunnel, reminding drivers to
either turn their headlights on or off. The solution was: "Are your
headlights on?" Does anyone know what book this was and what the
story was? The relevance here is that IMO the line in the
documentation only needs to be a "headlights" reminder, not a full
discourse on memory management.
</sidenote-and-question>
Worse, that isn't even accurate - you don't care if the object is
autoreleased or not (it may, for example, be a singleton that is
never actually released - for example [NSNumber numberWithInt: 0]
will return the same value every time you call it - the result isn't
autoreleased).
This just proves that "returns an autoreleased object" is the wrong
line to add. I'd suggest something like "You are responsible for
retaining the returned object."
My experience when I first learned it was that I tended to try to
over-think the situation. Once I realized that it really was as
simple as it seemed, it all just clicked.
My experience was similar, I think. Actually I don't remember; it
seems so natural now. Anyway, I'm not necessarily saying the docs
need this additional line, only that it wouldn't be so bad if it were
there, and a bit of judicious redundancy *might* help people learn the
rules a little more quickly.
In a similar vein, I think it's worth mentioning that -setDelegate:
doesn't retain the given object. Same for other methods where you
might expect the object to be retained.
--Andy
_______________________________________________
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]
