Mailing-List: contact directory-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Apache Directory Developers List"
 <directory-dev@incubator.apache.org>
Received-SPF: pass (hermes.apache.org: local policy)
From: "Noel J. Bergman" <noel@devtech.com>
To: "Apache Directory Developers List" <directory-dev@incubator.apache.org>
Subject: Commenting code
Date: Sun, 12 Dec 2004 10:18:21 -0500
Message-ID: <NBBBJGEAGJAKLIDBKJOPAENMOJAB.noel@devtech.com>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
In-Reply-To: <41BC00DE.9040006@bellsouth.net>
Importance: Normal

Alex wrote:

> I fixed this in the following revision:
> http://svn.apache.org/viewcvs?view=rev&rev=111644

One thing I am noticing, just as an example, is that when fixes are put into
the repository, we have a decent description of the fix in the commit log,
but comments are relatively sparse.

My general comment is that I'm not seeing code commented as if some other
programmer would have to work on it.  Yes, tend to have a description of
each method, and usually something on branch points, but I comments are
explanations to some other programmer (as well as reminders to ourselves
some months or years later) as to what the code is doing and why it is
important.

This observation is certainly not limited to this project, but reading
through recent commits inspired me to prod everyone to comment code.

	--- Noel