Print

---

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