Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Andrew White <email@hidden>
- Date: Mon, 11 Jul 2005 12:55:30 +1000
Andy Lee wrote:
On the other hand, I see sloppiness when it comes to *explaining* things.
> ...
Excellent thoughts, Andy. Sample code should be written under one of two
assumptions:
(1) The reader understands just the implementation language.
(2) The reader understands the language and the prior knowledge mentioned
somewhere in the header.
Beyond that, the writer should ask "Is there any information I'm using here
that is not visible simply from reading the code?". If so, document it.
Apple's classes use good naming so there's quite a bit you can get from
that, but don't assume that the reader has a conceptual model of what is
happening - that is what the sample code is supposed to help provide.
Orthogonal question: Is there any good documentation / examples on building
multi-windowed non-NSDocument apps (eg something like terminal)? My
current method is to build an NSDocument app and manually disable all the
file-linked stuff, but that feels yucky. If not, I'll file an enhancement
request for better support of this space.
--
Andrew White
Researcher, National ICT Australia
http://www.nicta.com.au/
+61 2 8374 5573
--------------------------------------------------------------------------
This email and any attachments may be confidential. They may contain legally
privileged information or copyright material. You should not read, copy,
use or disclose them without authorisation. If you are not an intended
recipient, please contact us at once by return email and then delete both
messages. We do not accept liability in connection with computer virus,
data corruption, delay, interruption, unauthorised access or unauthorised
amendment. This notice should not be removed.
_______________________________________________
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