Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Andy Lee <email@hidden>
- Date: Sun, 10 Jul 2005 10:04:21 -0400
On Jul 10, 2005, at 12:48 AM, mmalcolm crawford wrote:
I don't know about Apple's apps, but I think the code for even the
sample developer apps is less useful than it could be. IMO,
sample apps should be meticulously documented, and formatted for
clarity, with comments that are *more* expository than companies
normally use for internal code (which in practice often cuts
corners in documentation, though I personally don't believe it
should). The classes and methods in the sample code should be
documented with the same thoroughness, consistency, and quality of
writing as any AppKit class. And the code should be impeccably
formatted and free of sloppy tics (little things like using NULL
when nil is better style-wise).
This is certainly the goal that is aimed for, and I hope more
recent samples have been better at this, but where the goal is not
achieved it should be considered a bug...
Honestly, I do not see nearly the editorial discipline applied to the
code samples as compared to the other documentation. I'm talking
partly about the documentation of the code and partly about the code
itself. On the one hand, I see decent coding habits when it comes to
naming things. (I actually have to make a conscious effort to notice
that, because seeing how consistent the API is about naming things
has got me taking it for granted.) On the other hand, I see
sloppiness when it comes to *explaining* things.
I've been working with the SimpleStickies example project, so most of
my gripes spring from that:
* Missing README.rtf. Other sample apps, like TextEdit, have a
README.rtf that shows up at the top of the file list. It should give
an overview of the classes in the project and how they interact.
* Zero-information comments. Comments for accessor methods often
simply say, essentially, "gets X" or "sets X." First, I would leave
out the comment if it contains no information. Second, how about an
explanation of what X is, when it's even slightly non-obvious? The
Entity class has a name, a displayName, and an entityName. What's
the difference? Accessor comments would be a good place to explain,
especially for classes that are highly reusable, as Entity and many
other classes in SimpleStickies say they are.
* Begged questions. The SyncIt class has a preferredSyncMode. Why
would I prefer one sync mode over another, and when might some other
sync mode be used (which must sometimes be the case, because
otherwise it would just be called "syncMode")? The SyncIt class has
three types of "syncMode" ivar; as a user of the SyncIt API I might
not care, but as someone reading the source code implementation I'd
like an explanation of the differences, probably in the .h file next
to the ivar declarations.
* Inaccurate comments. I know that realistically comments sometimes
get of sync with code, no matter how meticulous one tries to be. But
when I see the comment for the -[SyncIt syncIt], which refers to a
method argument when there are clearly no arguments, I feel like no
one read this comment with an editorial eye before sending it out the
door.
* Long lines. I realize we aren't constrained by 80x24 terminals any
more, but must we have lines of source code that extend literally to
column 161? (See -[SyncIt changeRecordIdentifiers:].)
* Poor factoring. The SimpleStickies example isn't so bad, but the
ZenSync example has classes that are essentially copy-and-pastes of
each other. Charlton Wilbur wrote that he was concerned about "the
novice practice of cut-and-paste coding." I am especially concerned
when Apple's own published code adopts that practice.
It could be argued that sample code is just throwaway stuff, scraps
of internal experimental code tossed into a junkpile that developers
can scrounge in. I happen to believe the opposite -- that *especial*
care should be taken to make sample code exemplary, pleasant to read,
and easy to learn from. If there isn't a Sample Code Style Nazi at
Apple, I believe there ought to be one.
BTW, speaking of copy and paste, I just pasted this bulk of this
email into RadarWeb 4175360.
--Andy
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden