Code Formatting Guidelines

Consistently formatted code enhances readability, reusability, and longevity of code, which is a good thing, especially considering the effort (and expense) that goes into writing code in the first place. This document provides some basic guidelines for the formatting of code developed on this project.

General

• Document the code. No exceptions.
• It is generally a good idea to indicate the authors of the code (usually in the comment block for the file). This is especially helpful a couple years from now when trying to determine why something is implemented a particular way or to find the expert on the issue being examined.
• Write unit tests.
• Set your editor to use UTF-8 by default.
• Always at least make a list of external dependencies (libraries, tools, applications) and where to find them (if not included in version control).
• Avoid OS specific dependencies. If really necessary, always make a note of any OS specific dependencies introduced by a block of code, and always implement such a block in a way that replacing with another block that might be developed in the future would be a relatively trivial matter (e.g. don’t embed a bunch of win32 specific calls throughout the code- write an abstraction layer instead).

Java

The Java Programming Style Guidelines by GeoSoft provides a very readable, concise summary of some good conventions to follow while producing Java code. It is quite similar (identical?) to the document Code Conventions for the Java Programming Language, though I find the single page layout of the former to be more convenient.

In general, these conventions should be followed for all new Java code developed specifically for DataONE. Where code is extending an existing application, is may be more appropriate to utilize the convention utilized by other developers working with that project.

Use JavaDoc conventions for documenting code.

The important aspect is consistency with a goal towards readability. It’s easy for a compiler to interpret code, generally much harder for people.

Python

The Style Guide for Python Code (PEP-0008) should be followed for all Python code, with the following exceptions:

• indentation should use 2 spaces, not 4 as suggested by Guido and Barry. One space is too short, and four leads to a greater likelihood of having to split lines.
• Never use tabs for indenting. Set your editor to use soft tabs or replace tabs with spaces.
• Leave two blank lines between method definitions inside a class.
• If adding multiple classes in a file, separate them with a commented row of “=”
• To be more consistent with the Java conventions, use the suffix “Exception” (rather than “Error” as suggested in PEP-0008) when naming exceptions.
• Follow DocString conventions to document code. Use either the EpyDoc or Sphinx approaches, but do not mix them within the same application. In general, using Sphinx autodoc is the preferred approach and will produce cleaner documentation than JavaDoc. This implies using reStructuredText formatting conventions in the docstrings. Documenting Python provides an overview of using Sphinx for documenting python.