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
- Re: Writing Readable Code Joe Bohn
-
