path: root/doc/coding_standard/coding_standard.tex

\documentclass[letterpaper,10pt]{article}
\usepackage{url}

%opening/title
\title{libbash Coding Standard}
\author{Nathan Eloe}
\date{\today}

\begin{document}
\maketitle
\section{Introduction and Acknowledgements}
The majority of the coding styles in this document can be found at \url{http://www.mst.edu/~cpp/cpp_coding_standard_v1_1.pdf}.  Minor changes have been made to the standard outlined there for personal preference and consistency.
\section{Commit Messages}
Commit messages should contain a brief (50 characters or less) description in the first line, followed by a more verbose and explanatory statement.  The title explanation should have normal sentence capitalization, and the explanatory statements should use proper English grammar.
\section{File Names}
Files must be named descriptively.  Files that will be included should be indicative of the functionality they provide.  If the file provides a class, the name of the file and class should match.  The names of header and implementation files (in the case of a class) should match.
\subsection{File Extensions}
The following extensions will be used:\\
Header files: .h\\
Implementation files: .cpp\\
Templated implementation files: .hpp
\section{Project Files}
Code must be split into two types of files: header files and implementation files.  Header files may contain no implementation except functions that may be implemented in one line/command, for example accessor/mutator functions.\\
Implementation and header names must match.  A class prototyped in the file foobar.h must be implemented in foobar.cpp or foobar.hpp.\\
\subsection{Header files}
\subsubsection{The \#define guard}
All header files should have \#define guards to prevent multiple inclusion. The format of the symbol name should be LIBBASH\_PATH\_FILE\_H\_.\\
For example, the file foo/src/bar/baz.h in project foo should have the following guard:
\begin{verbatim}
#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_

/*
code
*/

#endif
\end{verbatim}
\subsubsection{Header file dependencies}
Don't use an \#include when a forward declaration would suffice.\\
\subsubsection{Names and Order of Includes}
Use standard order for readability and to avoid hidden dependencies: C library, C++ library, other libraries' .h, your project's .h.\\
All of a project's header files should be listed as descendants of the project's source directory without use of UNIX directory shortcuts . (the current directory) or .. (the parent directory).\\
In dir/foo.cc or dir/foo\_test.cc, whose main purpose is to implement or test the stuff in dir2/foo2.h, order your includes as follows:
\begin{verbatim}
1. dir2/foo2.h
2. C system files.
3. C++ system files.
4. Other libraries' .h files.
5. Your project's .h files.
\end{verbatim}
Use one blank line to separate each section. Within each section it is nice to order the includes alphabetically.
\subsection{Implementation Files}
Implementation files will NEVER be included by another file.  Files with the extension .hpp should only be included at the end of the header file of the templated class they are implementing.
\section{Comments}
We only add comments for public members and methods. Comments for protected/private members and methods are not required.
\subsection{File comments}
At the top of every file that has not been automatically generated, a comment block containing the file name, brief description in the following form (Doxygen style commenting) after the licence comment block:
\begin{verbatim}
///
/// \file: filename.h
/// \brief description of the file
///
\end{verbatim}
More information if needed may be added after the brief description.
\subsection{Class comments}
Any header prototyping a class should have a comment block containing the class name and a brief description:
\begin{verbatim}
///
/// \class class_name
/// \brief description of class
///
\end{verbatim}
More information if needed may be added after the brief description.
\subsection{Function comments}
Functional comments should appear in the header files in which they are prototyped.  In the case of a function that has no prototype, the functional comment will go directly before the function implementation.  The comment block should have the following form:
\begin{verbatim}
///
/// \fn function_name
/// \brief description of function
/// \return what the function returns
///
\end{verbatim}
\subsection{Class variables}
Member variables in a class should have the following comment block:
\begin{verbatim}
///
/// \var scope::variable_name
/// \brief description of variable
///
\end{verbatim}
\section{Program code}
\subsection{Indentation}
Every line inside of a code block should be indented for easier readability.\\
Tabs should not be used for indentation, only spaces.  Indentation width will be two spaces. \\
Tabs should be used for ANTLR grammar because antlrworks automatically generate tabs. \\
Tabs should also be used for autotools related files(Makefile.am, configure.ac, etc). \\
Use ts=4 for indentation.
\subsection{Line length}
We don't have strict line length limit but you shouldn't write a line that is too long to be read easily. In general, we should keep the line length under 110 characters.
\subsubsection{More indentation rules for tree walker grammar}
Put colon and the first alternative of a rule in the same line with no space between them.\\
Do not use space between the alternatives and '\textbar'.\\
Put left brace of the embedded action block and the rule in the same line with one space between them.\\
Use one space between rule name and 'returns'.
\subsection{Naming conventions}
The name of a variable, function, class, or struct should be obvious from it's name.\\
Names will use underscored names not mixed case.\\
One letter names may only be used as counters in loops or if the usage is obvious or widely accepted (x and y for coordinates, etc).\\
Global variables should not be used. Any global constant should remain constant and may not be modified.\\
Template names should be descriptive or conventional.
Class names should begin with lower case letters.
\subsection{Namespaces}
Namespaces should never be "use"d.  On using any STL class, it should be manually scoped:
\begin{verbatim}
using namespace std; //Not good
vector<string> names; //Not good
std::vector<std::string> names; //GOOD
\end{verbatim}
Namespaces may be used in implementation files if they do not cause conflicts, as implementation files should never be included in another file.
\subsection{Classes}
Use the C++ keyword explicit for constructors with one argument.\\
Provide a copy constructor and assignment operator only when necessary. Otherwise, disable them with "= delete" from C++0x.\\
Use a struct only for passive objects that carry data; everything else is a class.\\
Composition is often more appropriate than inheritance. When using inheritance, make it public.
\section{Statements}
\subsection{Simple statements}
Each line should contain only one statement:
\begin{verbatim}
int x=5; cout << x << endl; //bad

//the following lines are good
int x=5;
cout << x << endl;
\end{verbatim}
The comma operator should not be used to group multiple statements unless it makes the meaning clearer.
\subsection{Variable declaration}
Multiple variables may only be declared on one line if none of the values of the variables are being set. Example:
\begin{verbatim}
int x,y,z; //good
int x=5,y,z; //bad
int x=5; //good
int y,z; //good
\end{verbatim}
\subsection{Compound statements}
Any grouping of statements enclosed in braces is considered a compound statement, and should follow the following rules:\\
1) Any statements within the compound statement should be indented an additional two spaces from the surrounding code.\\
2) The opening brace should begin the line before the statements in the code block, and the closing brace should begin the line after the statements in the code block.  Example: \\
\begin{verbatim}
if (i==5)
{
  //code goes here
}

//NOT THIS
if (i==5) { /* code */ }
\end{verbatim}
The only exception to this rule is if the compound statement is a one line implementation of a mutator or accessor function in a header file.\\
3) Braces should be used around all statements, even if it is a single line following (as in a single command after an if statement).
\subsection{return Statements}
A return statement should not use parentheses unless they are needed to make the return value more obvious.  Examples:
\begin{verbatim}
return;

return my_list.size();

return (index<max_index? index : max_index);
\end{verbatim}
\end{document}