gnustep-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Public methods description should be in header files


From: Richard Frith-Macdonald
Subject: Re: Public methods description should be in header files
Date: Sun, 13 Oct 2002 06:07:02 +0100

On Sunday, October 13, 2002, at 02:00  am, Nicola Pero wrote:

Adam,

why have you moved comments and documentation from the public
NSSavePanel.h file to the private NSSavePanel.m file ?

I was startled by your change - it looks like you're trying to hide the
few comments/documentation we have. :-)

I read Adams comment in the ChangeLog ... and far from hiding information,
he says he's putting the info in the documentation!

Everyone having the headers installed can read the NSSavePanel.h; and the
headers are installed by default, and bundled by default with the
packages; while to read the NSSavePanel.m file you need the library source code, which is not installed by default, and if you're getting precompiled binaries, you need to download separately, and it contains actually a lot
of implementation details and code which the user needs not to know and
read about, as users not knowing how to use a class are notoriously
confused by not knowing what is public and what is private.

As he's put the info in the documentation ... which is where users should
be looking for it,  I think the above argument is misguided.

Comments explaining public methods _must_ be in public header files where the methods are publicly declared, and where developers using the library
can find/read them.

Information on public methods must be in the documentation ...
Having it in the headers too ought to be pretty irrelevant.

While I obviously cannot speak for Adam, I can think of two reasons for
moving from header to source.

1. (This one I strongly believe myself) If the source comments for the
documentation are stored in the .m rather than the .h files, library developers (working on the GNUstep code itself) are more likely to keep them up to date.

2. (I think a weaker reason) Removing comments from the headers should
encourage people to read the documentation, showing them that there is a
single location for reference information. I think Adam said recently that
improving documentation should be a major aim ... so this makes sense.

I'd even say it should be in our coding standards (if it's not there
already) ... every public method (actually, everything :-)) declared in a public header file should have a corresponding public comment in that same
header file explaining what the method does - and how to use it.

Well, I agree that we should document all public methods ... but I think that the place for people to read that is in the documentation. I don't think it is good if our users think they have to read both the documentation *and* the
headers.

I suppose you could argue that someone might have an installation with binaries
and headers but neither source nor documentation, but I don't think it's
unreasonable to insist that a developer intending to use the libraries should
install the library documentation.





reply via email to

[Prev in Thread] Current Thread [Next in Thread]