geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Bohn <>
Subject Re: Writing Readable Code
Date Mon, 18 Sep 2006 00:31:02 GMT

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

View raw message