Class/Method Header in source code

[Francois Orsini <fr...@gmail.com>]

What's the current policy in respect with coding standards in Derby?

I would like to suggest that there is an extra efforts in commenting source 
code and in particular class headers which are not there in lots of classes.

Due to the nature of Open Source, it is not like there are a lot of design 
documents lying around - providing a description of what a class does (does 
not have to be a novel) would be benefitial im my opinion (especially for 
large ones). Class headers make it to javadoc if properly formatted.

On the same subject, providing decent comments to methods and variables 
would be greatly benefitial as well. I'm hoping reviewers can check on these 
nd suggest additional comments if needed.

You can see some formatting examples under the following packages (amongst 
other places):
org.apache.derby.impl.jdbc
org.apache.derby.impl.jdbc.authentication

Not sure if this has to go through a vote or not. Maybe it has already been 
done already. Would love to see something around this being specified 
somewhere in the Derby community contributing area.

Thanks,

--francois

Re: Class/Method Header in source code

[Jeremy Boynes <jb...@apache.org>]

Francois Orsini wrote:
> What's the current policy in respect with coding standards in Derby?
> 
> I would like to suggest that there is an extra efforts in commenting source 
> code and in particular class headers which are not there in lots of classes.
> 
> Due to the nature of Open Source, it is not like there are a lot of design 
> documents lying around - providing a description of what a class does (does 
> not have to be a novel) would be benefitial im my opinion (especially for 
> large ones). Class headers make it to javadoc if properly formatted.
> 

Also due to the nature of open source, people are volunteers. Patches 
adding to or otherwise improving documentation would be greatly appreciated.

--
Jeremy