Commit e78b6b50 authored by Thomas Witkowski's avatar Thomas Witkowski
Browse files

Added code style directive.

parent 08a27a7c
\documentclass[a4paper]{article}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsfonts}
\usepackage{listings}
\title{AMDiS C++ code style directive}
\author{Thomas Witkowski}
\begin{document}
\maketitle
\section{General recommendations}
\begin{enumerate}
\item The main goal of this document is to assure a unique code style
in AMDiS. This should make the code more readable and easier to maintain.
\item The code should be readable independently of any text editor and
IDE.
\item Any violation to the guide is allowed if it enhances readability.
\item Not all source files of AMDiS are already converted to this
style. If you are bored, you are free to do it.
\end{enumerate}
\section{Naming conventions}
\begin{enumerate}
\item All names should be written in English.
\item Names representing types must be in mixed case string with upper case.
\begin{lstlisting}{}
FiniteElemSpace, ProblemInstat
\end{lstlisting}
\item Variable names must be in mixed case starting with lower case.
\begin{lstlisting}{}
refinementManager, fileWriter
\end{lstlisting}
\item Named constants (including enumeration values) must be all
uppercase using underscore to separate words.
\begin{lstlisting}{}
CALL_LEAF_EL, GRD_PHI
\end{lstlisting}
\item Names representing methods or functions must written in mixed
case starting with lower case.
\begin{lstlisting}{}
refineMesh(), getTimestep()
\end{lstlisting}
\item Abbreviations and acronyms must not be uppercase when used as
name.
\begin{lstlisting}{}
getFeSpace() // NOT: getFESpace()
listDof // NOT: listDOF
\end{lstlisting}
\item Do not use underscores to indicate variable scopes.
\item The prefix n should be used for variables representing a number
of objects.
\begin{lstlisting}{}
nPoints, nBasisFcts
\end{lstlisting}
\item Naming pointers specifically should be avoided.
\begin{lstlisting}{}
Line *line // NOT: Line *pLine
Element *el // NOT: Element *ptrEl
\end{lstlisting}
\end{enumerate}
\section{Files}
\begin{enumerate}
\item C++ header files should have the extension .h. Source files should
have the extension .cc.
\item A class should be declared in a header file and defined in a
source file where the name of the files match the name of the class.
\item All definitions should reside in source files. Usually, get- and
set-function can be excluded from this rule.
\item File content must be kept within 85 columns.
\item Include statements must be located at the top of a file only.
\end{enumerate}
\section{Statements}
\begin{enumerate}
\item Type conversions must always be done explicitly. Never rely on
implicit type conversion. Do not use C-style type conversion.
\begin{lstlisting}{}
floatValue = static_cast<float>(intValue);
// NOT: floatValue = intValue;
// NOT: floatValue = (float)intValue;
\end{lstlisting}
\item Variables should be declared where they are used for the first time.
\item Variables should be initialized where they are declared.
\item Use of global variables should be minimized.
\item Class variables should never be declared public.
\item Control variables in for() loops should be declared within the for-construction.
\begin{lstlisting}{}
for (int i = 0; i < 10; i++)
// NOT:
int i;
for (i = 0; i < 10; i++)
\end{lstlisting}
\item Complex conditional expressions must be avoided. Introduce
temporary boolean variables instead.
\item The conditional should be put on a separate line.
\begin{lstlisting}{}
if (isOkay) // NOT: if (isOkay) doIt();
doIt();
\end{lstlisting}
\item Executable statements in conditionals must be avoided.
\item Floating point constants should always be written with decimal
point and at least one decimal.
\begin{lstlisting}{}
double total = 0.0; // NOT: double total = 0;
double speed = 3.0e8; // NOT: double speed = 3e8;
\end{lstlisting}
\end{enumerate}
\section{Layout}
\begin{enumerate}
\item Block layout should be as follows
\begin{lstlisting}{}
if (isOkay) {
doSomething();
...
} else {
doSomethingElse();
...
}
for () {
runCode();
...
}
\end{lstlisting}
\item Single statement if-else, for or while statements can be written
without brackets.
\begin{lstlisting}{}
for (int i = 0; i < 5; i++)
doSomething();
// NOT:
for (int i = 0; i < 5; i++) {
doSomething();
}
\end{lstlisting}
\item The class declarations should have the following form:
\begin{lstlisting}{}
class SomeClass : public BaseClass
{
public:
...
protected:
...
private:
...
}
\end{lstlisting}
\item Method definitions should have the following form:
\begin{lstlisting}{}
void someMethod()
{
...
}
\end{lstlisting}
\item General white spaces:
\begin{itemize}
\item Conventional operators should be surrounded by a space character.
\item C++ reserved words should be followed by a white space.
\item Commas should be followed by a white space.
\item Colons should be surrounded by white space.
\item Semicolons in for statements should be followed by a space character.
\end{itemize}
\begin{lstlisting}{}
a = (b + c) * d; // NOT: a=(b+c)*d
while (true) // NOT: while(true)
doSomething(a, b, c, d); // NOT: doSomething(a,b,c,d);
for (int i = 0; i < 10; i++) { // NOT: for(int i=0;i<10;i++){
\end{lstlisting}
\item Methods should be separated by two blank lines.
\end{enumerate}
\section{Comments}
\begin{enumerate}
\item Tricky code should not be commented but rewritten!
\item All comments should be written in English.
\item Class and method header comments should follow the JavaDoc
conventions.
\end{enumerate}
\end{document}
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment