geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Dillon <ja...@planet57.com>
Subject Re: Writing Readable Code
Date Sun, 17 Sep 2006 20:19:59 GMT
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
>>


Mime
View raw message