Code Documentation

Top Comment

Java Example

/**
 * This class encapsulates concepts related
 * to input files of the VCF type
 * @author Joshua Lamos-Sweeney
 */

The start of a file should contain a language specific comment block specifying both the author (or authors, see below) of the document and a brief, one paragraph summary of the reason for the class.

If a significant change or addition is made to an existing class, the editor should put their name in the author field as well.

Class or file comment summarizes functionality of class or file
Author tag is present and appropriate

Method Comments

Note: This discussion is on public, Java, outward facing method comments. The current development team is of two minds as to the necessity of method comments on all methods. Use your best judgement on the merits of ‘self-documentation’ in code.

Java Example

/**
 * This method, given an input file, reads it for the specified column name and returns a link to a temporary file.
 * @param inputFile Input file in appropriate format
 * @param columnName Column name to be searched for. If this is null, searches for metadata.
 * @return File object referencing the temporary file created (caller will dispose)
 */

Publicly facing methods (methods called from outside this file or class, used by others on the team) should (se e info box) be documented in this style. This documentation will include a complete list of input parameters, a brief description of the output parameter(s), and a technical overview of what the function does.

Method summary is detailed enough to understand what the method does and when it can be used
Method inputs are described in detail
Method outputs are described in detail

Inline Comments

Java Example

//PriorityQueue implements a Heap Sorting algorithm on insert
for(item:list){
  pq.add(item);
}
for(item:pq){
  doIt(item); //Sorted!
}

Code blocks of sufficient detail should have inline comments explaining the technical details of how they work. This should not be Here Be Dragons, but instead should be of sufficient detail for a technically capable individual to decipher the intent of the code. Above example is not contrived, for once.

Long or Complex code segments have inline comments
Inline comments use as little 'invented language' as possible
Inline comments refer to the code on same line or directly following comment
Inline comments are up to date (refer to current code, not 'out of date')
No code in inline comments!

Confluence Documentation

Is this a new feature that end-users (or other programmers) may want to know about?
Is this a bugfix that changes how a system works?

Either way, a less technical document that gives an overview of how to use functionality may need to be created or updated.

Ask the lead developer if a confluence page makes sense
- A page about functionality ALWAYS makes sense if this is something that would go in a handbook on how to use the software
- A page about functionality OFTEN makes sense if the code is complicated and a maintainer will need to know how it works
- A page about functionality OFTEN needs to be updated when a significant overhaul is made to an existing feature
Confluence document is written for a general audience
- Appropriate terms are explained or linked to
- But may contain technical sections which may be very general audience unfriendly
Confluence document is either short (2 pages or less) or has appropriate headings
Confluence document is in the appropriate section, and is referenced from other documents related to the subject
- And has appropriate tags