Jason Dillon wrote:
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.
Sorry, I got a bit loose with my terminology. Yes, I agree with //
multi-line comment style and personally prefer that to /* ... */ style.
What I was more intending to avoid was the infamous 200 char code line
followed by a comment on the same line which I sometimes miss when I'm
just scanning code to get the general idea of what it's doing.
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.
Yes, I agree with this too. I was thinking of more interesting methods.
Getters, setters, and constructors are typically self-explanatory.
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
