path: root/doc/coding-standard.tex

\documentclass{article}
\usepackage{metatron}
\title{LedgerSMB Coding Standards}
\author{The LedgerSMB Development Team}
\begin{document}
\maketitle

\tableofcontents

\section{Introduction}
Consistent coding style contributes to readability of code.  This contributes in
turn to fewer bugs and easier debugging.

While consultants which implement custom solutions for their customers are not
required to follow these coding guidelines, doing so will likely contribute to
efficiency of the project and, if desired, the likelihood of having the changes
accepted in the main source tree.

\section{File Organization and Whitespace}

Files should be organized according to three principles: atomicity, performance,
and readability.  While there is no stated maximum file size, there is no reason to
group large amounts of code together when only a small subset of that code will
be executed on any given run of the program.  Similarly, core API for a single
data structure entity may be grouped together even if each run may touch only a
small part of the code so that these functions can be maintained together in a
logical way.

Nested blocks of code should be indented with a single 4 spaces.  Tabs are OK, 
but before release, a single commit will be made using perltidy -i=4.  

Lines longer than 79 characters are not handled well by many terminals and
should generally be avoided.  Continued lines should be indented by one more tab
than either the line above or below (i.e. if the line above is indented by two
tabs and the line below by three, indent the continued segment by four).

Lines longer than 79 characters cause problems in some terminals and should be
avoided.

\section{Comments}

In an ideal world, the code should be sufficiently readable to be
entirely understandable without comments.  Unfortunately, this sort of
ideal is seldom attained.  Comments should be used to annotate code
and add information that is not already a part of code or programming
logic itself.

Comments may include arguments and return values of functions (for
easy reference), a summary as to why a particular design choice was
made, or a note to alert future programmers that a particular chunk of
code deserves additional attention.  Comments should not, however,
merely indicate what the program is doing or how it does something.
If such comments are required, that is a good indication that a block
of code requires rewriting.

Additionally it is a good idea to provide a brief description at the top of each
file describing, in general terms, what its function is.

\section{Function Organization}

Functions should be atomic.  While there is no maximum length to functions, long
functions may be an indication that a function may be non-atomic.

In general, when more than one line of code is being copied and
pasted, it should instead be moved into its own function where it can
be called by all entry points.

\end{document}