[Top][All Lists]

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

Public methods description should be in header files

From: Nicola Pero
Subject: Public methods description should be in header files
Date: Sun, 13 Oct 2002 02:00:03 +0100 (BST)


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. :-)

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.

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.

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.

I suppose you were following some new/different convention of yours ?

reply via email to

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