geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anita kulshreshtha <a_kuls...@yahoo.com>
Subject Re: Writing Readable Code
Date Tue, 19 Sep 2006 13:00:21 GMT
     I have read a lot of code and found that the code is
understandable enough. However I found it was hard to get an overall
picture. 
   I agree with Kevan that "When a  method is a part of an overall
larger picture, pulling that context  together can be extremely useful
to the reader". Matt suggested that "for the person who is looking at
the code six months from now it might be nice to have part of that
discussion on the dev list condensed into the code in the form of a
comment". IMHO, it would be better to put this condensed discussion in
the Jira issue that was used to commit the code. The code should have a
link to this issue. We should make sure that this informal design
document includes all the explanations/issues raised by the community
but still be high level enough to be not affected by minor tweaks in
the implementation. A finished document for the wiki is even better but
not required.
   Other than this I agree with Paul that " low bar for committing to
trunk should be that it compiles, does no harm, and has undergone
adequate discussion within the Dev community.  Providing adequate
comments lies just outside that threshold as something that you should
expect to be nagged heavily about but not necessarily vetoed."

Thanks
Anita

--- Kevan Miller <kevan.miller@gmail.com> 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
>   
> 


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 

Mime
View raw message