diff --git a/doc/codeStyle.pdf b/doc/codeStyle.pdf new file mode 100644 index 0000000000000000000000000000000000000000..269678587d8547417b6be5be165862d1049937dd Binary files /dev/null and b/doc/codeStyle.pdf differ diff --git a/doc/codeStyle.tex b/doc/codeStyle.tex new file mode 100644 index 0000000000000000000000000000000000000000..36ac4b6655cc7015396de9094b6149d2639d8232 --- /dev/null +++ b/doc/codeStyle.tex @@ -0,0 +1,231 @@ +\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