This course has already ended.
  1. COMP.CS.140
  2. 10. Work Distribution and Working in a Team
  3. 10.2 Documentation and Conventions

Documentation and Conventions

Documentation is an important but easily omitted part of software development. Therefore the aim has been to processes and practices that produce sufficient documentation naturally as part of development work.

Documentation of Software

The documentation of a piece of software can be a separate document alongside the source code or included into the code itself. The documentation is a description of the software, how it works, how it was implemented and how it should be used. For a software developer, the documentation should tell at least:

  1. The specification of the software, i.e. the requirements of the software

  2. The architecture of the software

  3. Code level documentation: interfaces, code comments

  4. Implementation history: typically this is covered by the history of the project in the version control log

  5. User manual

  6. …

Documentation always has a target audience. Documentation can be targeted to people inside the project of to external people. A good documentation take sthe target audience into account and at the same time is regardless of the target audience:

  • clear

  • concise

  • comprehensive

  • contains all necessary information

  • contains nothing unnecessary

Working Software over Comprehensive Documentation

In agile software development and the agile manifesto the emphasis is on the importance of the software over documentation. This does not indicate that documentation is futile. The emphasis is, however, that the documentation covers on ly things that are relevant to the different stakeholders. No documentation is done for documentation’s sake.

Software documentation comprises several data sources. For example:

  • class diagrams

  • README files

  • Change logs

  • Interface documentation

  • Version control logs

  • User manual

are considered as a part of the documentation.

How to comment code

Earlier you have been taught that code must be commented. This holds for small programs. With large programs the program code itself should no be commented. Commenting is focused toward documenting interfaces with a code comment format. The reason behind a minimalistic commenting of code is simple: code should be otherwise so clear that it doesn’t require separate explanations. In addition each comment line is also a line in the code that needs to be refactored to match the renewed implementation. On code level commenting is left for situations where some implementation detail needs explanation or reasoning. Let’s take an example to highlight the change is commenting:

/* if allocation flag is zero */
if ( alloc_flag.equals( 0 ) )
// The comment does not give any additional information that is not already evident in the code

/* if allocating new member */
if ( alloc_flag.equals ( 0 ) )
// The comment clarifies the purpose of the code. Magic number 0 still just obfuscates the code

/* if allocating new member */ //<- no need for the comment with good naming conventions in code
if ( alloc_flag == NEW_MEMBER )

Other conventions

It is important to agree on work distribution between team members and to follow it during implementation. Simple methods are typically the best. For example the so called Kanban board helps to follow and prioritize coding effort. In addition it can be used to follow the progress of developers. The Kanban board in in practice post-it notes on a whiteboard where one note is one piece of implementation. The note moves on the board fromn one statge to another, one column to another. Typical columns are: backlog, under development, stuck and done, but the team can plan their boards freely. An easy and free tool to implement the boards is Trello.

The role of code conventions is to make sure that each team member writes uniform code. This improves the readability and quality of code and keeps the entire codebase uniform. Things to agree upon include for example:

  • Commenting (incl. Interface documentation JavaDoc)

  • Indentation: always indent code with spaces. IDEs can be configured to use a sensible amount of spaces as indentation when tabulator key is pressed (or they do so automatically).

  • Line length: code is typically short so a reasonable line length makes sense. The classic length is 79 characters.

  • Naming: it is good to write code with a uniform language choice and to agree upon a uniform way to name functions, variables, constants etc.

  • Coding practices and principles, rules of thumb: for example subclass methods that override baseclass implementations are marked with @Override or that exceptions caught are never left unhandled.

  • Other style issues: placement of braces, spacing and empty lines, use of annotations etc.

An example of a Java style guide is Google Java Style Guide.

Code review i.e. improving the quality of code by reading it through thinking:

  • Does it do what is should do,

  • Does it follow the coding conventions

  • Does it contain functional errors.

is a good way to catch hard to detect errors and problems in the code. The most fluent way to implement code review is to attach it to version control work practices so that no code is added to the main branch directly but always through a separate pull/merge request.

Other practices that need to be agreed upon relate to version control. At least to following needs to be agreed upon:

  • how branches are used

  • how the program is tested

  • when to deploy and who can deploy into production

  • what must be included in commit messages

Posting submission...