Color comments to some hideous color so you can't miss them. block
comments in code is a pain the ass when you need to comment out
something. I personally never easily miss a // comment :-P, but then
again, I normally make comments in code using // multiline with NOTE:
or HACK: or TODO: which IDEA likes to add extra color too.
I think at the minimum that classes *must* all have javadoc...
forcing each method to have javadoc is lame and will endup with lame
javadocs that are meaningless... like getName() this method gets the
name, setName() this method sets the name. But, I am generally in
favor of javadocs, and package docs. Wish more of G had them... pity
that it doesn't.
IMO what to doc and what not to doc just comes naturally to me... and
I like to add them as it augments the readability of the code and the
beauty too... maybe I am a dork, but I like to javadoc my code and
then go read the generated html... makes me feel good.
--jason
On Sep 17, 2006, at 1:05 PM, Joe Bohn wrote:
I completely agree.
There are some areas of the code that contain virtually no
comments. Any comments are better than none. Better still would be
some guidelines as you've suggested.
At a minimum I think that each method should have javadoc style
comments that actually explain the purpose of the method as opposed
to simply echoing the obvious (param name/type definitions and
return types). I think that descriptive comments highlighting the
purpose of the method are most helpful. I also prefer block
comments at critical places in the code to describe the flow over
EOL comments which are easily missed.
Joe
Kevan Miller wrote:
During the recent discussions regarding the Geronimo Development
process, several people expressed some concern about moving away
from RTC. The biggest issue seemed to be that RTC insured
multiple people reviewed new code. Having reviewed the code, the
reviewers now understood and would be able to support the code
(i.e. fix bugs).
This is certainly a valid concern. However, even though we're now
following CTR, we all need to be making a concerted effort to
provide the same level of review as commits are made.
No matter what process we're following, IMO, the best way to
insure that people are reading *and* understanding your code is
to write code that is easy to read and understand. This does not
mean writing simple code. It simply means keeping the reader in
mind and trying to make their job easier.
The single, most important thing, in my mind, is to provide clear
and insightful comments to assist the reader. These don't need to
be verbose tomes. They don't need to state the obvious. However,
any assistance you can provide the reader is helpful. Describe
the processing flow that methods are being invoked. What are the
threading assumptions? Identify subtleties that a reader might not
be aware of. Who are the potential callers? etc...
In case anyone is wondering -- I think we've been lacking in this
department. I'd like to see simple comment guidelines
incorporated into the Documentation Guidelines for our CTR process.
In my opinion, failure to appropriately comment new code is cause
for a commit to be vetoed. I doubt that this will happen often. I
expect that in most instances these issues can be resolved
appropriately through simple discussion. Some basic rules-of-
thumb are likely to help resolve any issues.
What do others think?
Specific ideas on comment guidelines? Javadoc-style comments for
APIs/ SPIs, etc? What types of comments should be expected?
--kevan
