Hi,
As I brought up in the software meeting today, a lot of our Java code is lacking even the most basic documentation.
I have made a list of files which do not have any class documentation at all in them.
http://java.freehep.org/svn/repos/hps/show/java/sandbox/MISSING_DOC.txt
I would appreciate all HPS Java contributors scanning over this list. If you are the primary author of a file, please add basic class documentation to it.
Especially, the ECAL readout simulation and the tracking module are not at all well documented.
The class documentation can be in the form:
/**
* This class does something super special.
* @author My Name <[log in to unmask]>
*/
class MyClass {
}
Adding javadoc to methods, at least all public ones, would also be nice, but I realize this is more time consuming.
Documenting methods looks something like:
/**
* My super special method.
* @param p This param does nothing.
* @return The answer to life the universe and everything.
* @throws IllegalArgumentException If your argument is invalid.
*/
public int doSomething(Object p) {
if (p == null)
throw IllegalArgumentException("Your argument is invalid.");
return 42;
}
I will be making an effort to contact individuals about their code soon if this documentation is not added in a reasonable time frame.
If you have questions about this, even "dumb" ones, then please ask.
Thanks.
--Jeremy
########################################################################
Use REPLY-ALL to reply to list
To unsubscribe from the HPS-SOFTWARE list, click the following link:
https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=HPS-SOFTWARE&A=1
|