Re: Trying to understand -- please help...

FROM : Andy Lee
DATE : Thu May 22 22:08:04 2008

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