geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Bohn <joe.b...@earthlink.net>
Subject Re: Writing Readable Code
Date Sun, 17 Sep 2006 20:05:28 GMT
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
>  
> 

Mime
View raw message