Developers

Good practice in PyTom

Document your code

It is not easy for others to figure out what the purpose of a specific routine is. Even the programmer him- or herself may have trouble remembering what the purpose of some piece of code was weeks or months after writing it. Thus, it is more than a good habit to document each routine.

PyTom uses http://epydoc.sourceforge.net for documentation. Epydoc is a lightweight documentation tool, which generates neat a neat html site for PyTom. For the current stable release you can find the documentation on http://strubi.chem.uu.nl/pytom/doc/epydoc/index.html. The underlying html is generated from the pytom source code.

Here is an example of how a pytom function should look like:

"""
some informative line about the entire file (all the good functions in there)
"""
def myCoolFunction(particleList, optionalStringParameter=None, 
        optionalIntegerParameter=1, verbose=False):
    """
    @param particleList: pytom particle list
    @type particleList: L{pytom.basic.structures.ParticleList}
    @param optionalStringParameter: this parameter does x (default: None)
    @type optionalStringParameter: C{str}
    @param verbose: Print out infos (for debugging)
    @type verbose: C{bool}
    @return: something really cool
    @rtype: C{int}
    @author: a really good programmer
    """
    from pytom.basic.structures import ParticleList
        
    some really good stuff
    
    return coolstuff

You can create the epydoc manual for your own GIT repository (i.e., including your documentation of ''myCoolFunction'') by running the script generateDoc.sh in the folder doc. In the folder doc/epydoc many html files will be generated. You can view the pytom html by loading the file doc/epydoc/index.html with your favourite browser.

---