Man cannot rely on headers alone (was Re: Docs)
Man cannot rely on headers alone (was Re: Docs)
- Subject: Man cannot rely on headers alone (was Re: Docs)
- From: Ken Tabb <email@hidden>
- Date: Fri, 24 Aug 2001 12:50:46 +0100
And so it was that Georg Tuparev said on 24/8/01 11:45 am:
>
> You shouldn't have to look at the headers in order to understand the
>
> framework and its behavior. This is only the evidence of a bad
>
> documentation
>
> or a bad implementation. Cocoa users suffers from a lack of
>
> documentation,
>
> not deficiency in C programming. Of course, we are unfortunately not
>
> all of
>
> us voodoo programmers, but you will teach us.
>
>
Again, one of these non Cocoa principle you might learn while studying
>
general programming technics is called DRY (Don't Repeat Yourself).
>
Rarely only technical writers (not only Apple's tech writers) a are the
>
people who cut the source. So these technical writers have to learn the
>
functionality themselves (and in most cases they do it from the headers)
>
in order to write documents. Unfortunately this brakes the DRY
>
principle, and the documentation is often out of sync. Therefore, not
>
only I, but many folks on this list will recommend you to consult the
>
headers.
Arguably if we're all meant to be reading the headers, why are they
buried so far down, and why has Apple made a partial attempt at providing
'proper' (i.e. navigable) documentation, in the form of the HTML AppKit /
Foundation docs (and PDFs)? And why aren't the headers provided on the
website, like the incomplete HTML docs? Methinks Apple (rightly so) don't
expect us to have to read the header files, otherwise they'd say as much
and provide easy ways of sifting through them.
Headers do serve a purpose, but the comments in them are generally
limited in scope to covering the class / procedures declared in the
header, and not necessarily integration with other technologies. For
instance you would not expect to find notes in the (Carbon) QuickTime
Framework headers discussing how to get the frame of a QuickTime movie as
a Cocoa NSImage. At least if you do expect that, you will be sorely
disappointed. Equally in the AppKit headers, the NSMovie class is such a
shell to a Carbon movie that it only discusses how to get the Carbon
movie, not how to get things from the Movie in a Cocoa object-oriented
manner. Neither of these headers discuss integration. That's one
example... there are many many others which headers do not (and should
not have to) cover.
So while I think headers are useful, they shouldn't *have* to be the
place to go. As the previous lister mentioned, that we have to use header
files as sources of documentation only goes to highlight how incomplete
the 'official' documentation is. And that Apple is half way (you can
decide whether or not I'm being generous by saying 'half'!) towards
providing 'offficial' (eg. HTML / PDF based) documentation, says that
Apple too does not expect us to have to go sifting through the headers.
Or maybe I'm wrong.
Ken
----------------------------------------------
Ken Tabb
Mac & UNIX Propellerhead & Network Bloke (Health & Human Sciences)
Computer Vision / Neural Network researcher (Computer Science)
University of Hertforfdshire
e-mail: email@hidden
http://www.health.herts.ac.uk/ken/
Certified non-Microsoft Solution Provider