% This file was converted to LaTeX by Writer2LaTeX ver. 1.4
% see http://writer2latex.sourceforge.net for more info
% \documentclass{article}
% \usepackage[utf8]{inputenc}
% \usepackage[T1]{fontenc}
% \usepackage[english]{babel}
% \usepackage{amsmath}
% \usepackage{amssymb,amsfonts,textcomp}
% \usepackage{array}
% \usepackage{supertabular}
% \usepackage{hhline}
% \makeatletter
% \newcommand\arraybslash{\let\\\@arraycr}
% \makeatother
% \setlength\tabcolsep{1mm}
% \renewcommand\arraystretch{1.3}
% \title{Programmierrichtlinien ANON}
% \begin{document}
% \clearpage\setcounter{page}{1}
\part{Programmierrichtlinien AN.ON}
\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip

Project AN.ON

\begin{center}
\begin{minipage}{7.303cm}
Projekt AN.ON

Hannes Federrath, Universität Regensburg 

Stefan Köpsell, TU Dresden


\bigskip

http://www.anon-online.de
\end{minipage}
\end{center}

\bigskip

Programming Standards


\bigskip


\bigskip


\bigskip

Stefan Köpsell

Rolf Wendolsky\newline
Derek Daniel


\bigskip


\bigskip


\bigskip

Version: 3.04


\bigskip


\bigskip

from: 2. February 2017


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip


\bigskip

Summary


\bigskip

This document contains the obligatory programming standards for developing the AN.ON project.


\bigskip


\bigskip

History


\bigskip

\begin{center}
\tablefirsthead{\hline
Version &
Datum &
Author(s) &
Description\\}
\tablehead{\hline
Version &
Datum &
Author(s) &
Description\\}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{|m{1.56cm}|m{1.714cm}|m{3.1cm}|m{9.406cm}|}
\hline
0.01 &
05.02.04 &
Rolf Wendolsky &
First version\\\hline
0.02 &
17.02.04 &
Rolf Wendolsky &
Added Variable Names\\\hline
0.03 &
17.02.04 &
Rolf Wendolsky &
New document structure, Split {\textquotedbl}Code Structure and Documentation{\textquotedbl}; Naming Conventions, Threads, Primary Goals, Libraries\\\hline
0.04 &
18.02.04 &
Rolf Wendolsky &
Partially new structure, Added: Simple Data Types, Other Conventions, Testing, more details for Libraries; Version Management removed\\\hline
0.05 &
\raggedleft 18.02.04 &
Stefan Köpsell &
A few notes\\\hline
0.06 &
\raggedleft 18.02.04 &
Rolf Wendolsky &
Notes taken into account; small addition to {\textquotedbl}Testing{\textquotedbl} chapter\\\hline
0.07 &
\raggedleft 20.02.04 &
Rolf Wendolsky &
Appendix\\\hline
0.08 &
\raggedleft 26.02.04 &
Stefan Köpsell &
Minimal changes, first public version\\\hline
1.00 &
\raggedleft 26.02.04 &
Rolf Wendolsky &
Changed format, made public\\\hline
1.01 &
\raggedleft 26.02.04 &
Rolf Wendolsky &
Grammatic errors removed, minor corrections, formating\\\hline
1.02 &
\raggedleft 26.02.04 &
Rolf Wendolsky &
Minor corrections\\\hline
1.03 &
\raggedleft 27.02.04 &
Rolf Wendolsky &
Minor corrections\\\hline
1.04 &
\raggedleft 04.03.04 &
Rolf Wendolsky &
2.1.1 changed\\\hline
1.05 &
\raggedleft 05.03.04 &
Rolf Wendolsky &
Minor corrections\\\hline
1.06 &
\raggedleft 11.03.04 &
Stefan Köpsell &
Minor corrections, Version number obtained from properties field\\\hline
1.07 &
\raggedleft 01.04.04 &
Rolf Wendolsky &
Line length change, additional documentation, added to Naming Conventions for variables, Makefile, CppUnit chapter corrected\\\hline
1.08 &
\raggedleft 08.04.04 &
Rolf Wendolsky &
Minor corrections\\\hline
1.09 &
~
 &
~
 &
~
\\\hline
1.10 &
\raggedleft 10.09.04 &
Rolf Wendolsky &
Testing of private members\\\hline
1.11 &
\raggedleft 22.09.04 &
Rolf Wendolsky &
Module tests are now required; Changes to Testing of private members\\\hline
1.12 &
\raggedleft 23.09.04 &
Rolf Wendolsky &
Minor corrections\\\hline
1.13 &
\raggedleft 01.10.04 &
Rolf Wendolsky &
Static Code/Singletons\\\hline
1.14 &
\raggedleft 14.10.04 &
Rolf Wendolsky &
Interface Immutable...,

various corrections\\\hline
1.15 &
\raggedleft 18.10.04 &
Rolf Wendolsky &
Update to Unittests and to Constants\\\hline
1.16 &
\raggedleft 07.11.04 &
Rolf Wendolsky &
Corrections to JUnit\\\hline
2.00 &
\raggedleft 09.06.05 &
Rolf Wendolsky &
General re-working:

Removed {\textquotedbl}Status{\textquotedbl} from the History,

Libraries-{\textgreater}XML, Type Conventions-{\textgreater}Threads,

Goals, Internationalization, ...\\\hline
3.00 &
26.10.05 &
Derek Daniel &
Partially translated into english\\\hline
3.01 &
22.11.05 &
Rolf Wendolsky &
Nomenclature and editing of Java messages\\\hline
3.02 &
\raggedleft 16.01.06 &
Rolf Wendolsky &
Nomenclature of images in Java,

Coding conventions\\\hline
3.03 &
08.10.06 &
Rolf Wendolsky &
Coding conventions for if-statements\\\hline
3.04 &
11.10.06 &
Rolf Wendolsky &
StringBuffer replacement\\\hline
\end{supertabular}
\end{center}

\bigskip

\clearpage
\bigskip

\setcounter{tocdepth}{2}
\renewcommand\contentsname{Table of Contents}
\tableofcontents

\bigskip


\bigskip

\clearpage\section{Introduction}

\bigskip

This document describes the programming standards for the AN.ON project. It provides a framework for writing project-specific code. The project goals in Chapter 2 should be achieved with the help of this framework. The Sun Coding Standards are the general basis for the project programming standards; Differences and additional guidelines are given. Free external sources may deviate from these standards. Since AN.ON is essentially split among the Mixproxy, written in C++, and the JAP/InfoService/MixConfig, written in Java, the programming standards for the two parts differ slightly. However, unless otherwise noted, the following guidelines are identical for both the Mixproxy/C++ and \ JAP/InfoService/Mixconfig/Java.


\bigskip

The central AN.ON management will ensure that the standards are followed.

\clearpage\section{Primary Goals}
\label{bkm:Zielsetzungen}
\bigskip

The Programming guidelines support the primary goals listed in this section. The goals are listed in order of significance with the higher-ranked goal taking priority over the lower-ranked goal in case of a conflict.


\bigskip

\subsection{Security}

\bigskip

\subsubsection{JAP/InfoService/MixConfig}
In anonymity mode, only encrypted data may be sent and the data may only be sent to the first mix in a cascade. Other than that data, the client may communicate only with a certified Infoservice to obtain mix cascade IP addresses or to obtain public keys from mixes, or with the central update server in order to obtain automatic updates. This restriction may change in the future with the planned introduction of a payment system, which would require communication with the account instance.

The JAP client cannot be used as a backdoor or similar point of attack in the user's system.


\bigskip

\subsubsection{Mixproxy}
Exploits must be prevented at all costs. Denial of service attacks (DoS) must be prevented as much as possible. Code should be written so that all data sent to the mix can be examined in detail. The mix may only be controlled by the user who has administrator access rights to the Mixproxy.


\bigskip


\bigskip

\subsection{Compatibility}

\bigskip

\subsubsection{JAP/InfoService/MixConfig}
The portability of the complete program to as many other platforms as possible must be ensured.


\bigskip

\subsubsection{Mixproxy}
The portability of the source code to as many other platforms as possible must be ensured.

\clearpage\subsection{Performance}

\bigskip

\subsubsection{JAP/InfoService/MixConfig}
Good performance is not a mission-critical goal for the JAP/InfoService/MixConfig part, but is always welcome. The quality of the code is more important in this case.


\bigskip

\subsubsection{Mixproxy}
Good performance in the Mix, however, is important and is a critical project goal. Therefore, speed is more important than robustness for this part of the code. Additional code tests may certainly be built into the debug mode, however.


\bigskip


\bigskip

\subsection{Quality}

\bigskip

The following points are listed in order of importance:


\bigskip

\begin{itemize}
\item Readability \ \ \ \ \ \ \ \ (...for other programmers)
\item Maintainability\ \ \ \ \ \ \ \ (short turn-around for changes)
\item Correctness\ \ \ \ \ \ \ \ (the correct output results from an appropriate input)
\item Error tolerance\ \ \ \ \ \ (no crashes, useful error messages)
\item Re-usability \ \ \ \ \ \ \ \ (...in other contexts / in other projects)
\end{itemize}
\clearpage\section[Structure]{Structure}
\label{bkm:Struktur}
\bigskip

\subsection{Package Structure}

\bigskip

A specific directory and storage structure must be followed for the JAP/InfoService files and the Mix. Files that are no longer used should be removed immediately.


\bigskip

\subsubsection{JAP/InfoService}
The following directories are important for development:


\bigskip

\begin{itemize}
\item certificates\ \ \ \ ({\textquotedbl}trusted{\textquotedbl} root certificates) 
\item doc\ \ \ \ \ \ \ \ (Javadocs)
\item documentation\ \ (automatically or manually created code documentation)
\item help\ \ \ \ \ \ \ \ (documentation for the JAP user interface)
\item images\ \ \ \ \ \ \ \ (pictures / graphics / icons for the JAP client)
\item JapDll\ \ \ \ \ \ \ \ (libraries for special functions in Windows)
\item src\ \ \ \ \ \ \ \ (source code)
\item test\ \ \ \ \ \ \ \ (source code for test cases; alternative source code directory)
\end{itemize}

\bigskip

The source code uses the following main packet paths:


\bigskip

\begin{itemize}
\item anon \ \ \ \ \ \ (everything necessary for the connection to the Mix)
\item forward\ \ \ \ \ \ (forwarder functionality and blocking resistance function)
\item gui\ \ \ \ \ \ (GUI classes)
\item jap\ \ \ \ \ \ (main functionality of JAP)
\item infoservice\ \ (main functionality of the InfoService)
\item jarify\ \ \ \ \ \ (classes for automatically creating jar files)
\item logging\ \ \ \ \ \ (logging classes)
\item misc\ \ \ \ \ \ (everything else)
\item proxy\ \ \ \ \ \ (local proxy functionality)
\item update\ \ \ \ \ \ (classes for Automatic Update)


\bigskip
\end{itemize}
The subpackages are arranged by their implemented functions.


\bigskip

\subsubsection{Mixproxy}
There are no packages in the first mix. For compatibility reasons, namespaces may not be used. However, classes may be organized by component name. Thus, the names of classes related to the Mixproxy all begin with CA.

Central settings, error codes, and includes that are used in every class can be found in the file StdAfx.h.


\bigskip

\subsubsection{Test Cases – Java}
Test cases and test classes must be placed in the \ test directory, which must also have the same packet structure as \ src. In the IDE, it will then appear that the production code and test code are in the same directory. In reality, the tests are separate from production code and are not allowed to be required for running the program.

For each package, there is a corresponding test package, for example jap.test, in the \ test directory, where the module tests for the package can be found. The module tests are thus visually separated (in the IDE) from production code, but correspond to each package.


\bigskip

\subsubsection{Test Cases – C++}
The test cases are in the test directory.


\bigskip


\bigskip

\subsection{Makefile – Adding Classes (C++)}

\bigskip

If classes are to be added to or removed from the project, it is not sufficient to simply do so within the IDE. You must also change the Makefile.am file (in the project's main directory) with the help of a text editor.

Be sure to save the file in UNIX format.


\bigskip


\bigskip

\subsection{Code Structure}

\bigskip

Each source file in the project has a required structure that will be described in the following sections.


\bigskip

\subsubsection[\ Java]{\ Java}
Java source files contain the following elements in exactly this order:


\bigskip

\begin{itemize}
\item disclaimer
\item package statements
\item {\textless}empty line{\textgreater}
\item import of Java sources \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (zero, one or more)
\item import of external library sources\ \ \ \ \ \ \ \ (zero, one or more)
\item import of project sources \ \ \ \ \ \ \ \ \ \ \ \ (zero, one or more)
\item {\textless}empty line{\textgreater}
\item class and interface descriptions
\item class and interface definitions
\end{itemize}

\bigskip

Imports with a * (for example, java.lang.*) are not permitted. Instead, each imported class must be listed individually. Imports that are no longer used must be removed immediately. Modern development environments can handle such removal automatically, for example, {\textquotedbl}optimize imports{\textquotedbl} in JBuilder.


\bigskip

\subsubsection[\ C++ Header Files]{\ C++ Header Files}
Header files must contain the following components in exactly this order:


\bigskip

\begin{itemize}
\item disclaimer
\item \#ifndef \_\_CLASSNAME\_IN\_UPPERCASE\_\_
\item \#define \_\_CLASSNAME\_IN\_UPPERCASE\_\_
\item {\textless}empty line{\textgreater}
\item \#include {\textless}project sources{\textgreater} \ \ \ \ \ \ \ \ \ \ \ \ (zero, one or more)
\item {\textless}empty line{\textgreater}
\item class description
\item {\textless}empty line{\textgreater}
\item \#endif


\bigskip
\end{itemize}
There should be no methods implemented in header files (inline) unless the function is trivial (for example, get and set methods).

Macros (for example, \#ifdef, \#define) are only permitted to turn a specific functionality on or off (for example, Mix with or without a payment method). An \#ifdef \_DEBUG (together with \#endif) is allowed for debug purposes.


\bigskip

\subsubsection[\ C++ Program Files]{\ C++ Program Files}
Program files must contain the following elements:


\bigskip

\begin{itemize}
\item disclaimer
\item {\textless}empty line{\textgreater}
\item \#include {\textquotedbl}StdAfx.h{\textquotedbl}
\item \#include {\textquotedbl}classname.hpp{\textquotedbl}
\item \#include {\textless}project sources{\textgreater} \ \ \ \ \ \ \ \ \ \ \ \ (zero, one or more)
\item {\textless}empty line{\textgreater}
\item class definition
\end{itemize}

\bigskip


\bigskip

\subsection[Classes{}- / Interface Structure]{Classes- / Interface Structure}

\bigskip

\subsubsection[\ Java]{\ Java}
A class or interface should be constructed as follows, although not all parts are necessarily present, especially for interfaces. Also, some parts are only allowed under special circumstances.


\bigskip

\begin{itemize}
\item final public static constants
\item final protected static constants
\item final private static constants
\item private static attributes
\item private attributes
\item constructor(s), including logical create-constructors
\item public class functions (static)
\item public member functions
\item protected class functions (static)
\item protected member functions
\item package (without a label) class functions (static)
\item package (without a label) member functions
\item private class functions (static)
\item private member functions
\end{itemize}

\bigskip

Anonymous classes should be avoided because they would adversely affect readability, maintainability and conformity.


\bigskip

\subsubsection[\ C++ ]{\ C++ }
Class elements must be strictly ordered in the following order of visibility:


\bigskip

\begin{itemize}
\item public
\item protected
\item private
\end{itemize}

\bigskip

The elements within each visibility area (scope) must be ordered as follows:


\bigskip

\begin{itemize}
\item static const constants
\item const constants
\item attributes (static)
\item attributes
\item constructor(s), including logical create-constructors (for example create(), getInstance())
\item destructor
\item class functions (static)
\item member functions
\end{itemize}

\bigskip


\bigskip

\subsection{Methods}

\bigskip

Normally, local variables should be declared at the beginning of a method. Variables that are only needed briefly (for example, in loops) should be declared later at the time they are used.

Tip: \ If a group of variables appears somewhere in the middle of a method, it's a good indicator that the method should be split into two methods.

\clearpage\section{Libraries}
\label{bkm:Bibliotheken}
\bigskip

\subsection{Internationalization (JAP/MixConfig)}

\bigskip

All character chains in JAP/MixConfig can easily be internationalized, in other words, expressed in multiple languages. The property files JAPMessages and MixConfigMessages serve this purpose. All strings that could appear in dialogs for the user must be deposited in these files. These strings can then be called in the program through the gui.JAPMessages class. The class also allows the use of placeholders for variables.


\bigskip

The property files must be edited with the JRC editor which is available at\newline
\ \ http://www.zaval.org/products/jrc-editor

It is based on Java and should run on all currently available systems.


\bigskip


\bigskip

\subsection{Logging}

\bigskip

The JAP/InfoService/MixConfig and Mixproxy use their own logging components. For this reason, System.out.println() and printStackTrace() (in Java) and cout (in C++) are forbidden when code is checked in!


\bigskip

\subsubsection{JAP/InfoService/MixConfig}
The class logging.LogHolder is responsible for logging. Output occurs through the static methods

\ \ \ \ log(int logLevel, int logType, String message) 

\ \ \ \ log(int logLevel, int logType, Exception exception) 

The logLevel is entered as a static constant in the LogLevel class and is accessible as \ LogLevel.LOGLEVEL. There is a total of eight different log levels that can be used depending on the importance of the output: DEBUG, INFO, NOTICE, WARNING, ERR, EXCEPTION, ALERT and EMERG. Only the outputs whose log level is equal to or higher than the configured log level will be written to the log file.

The logType is a static constant in the LogTypes class and is accessible as LogTypes.LOGTYPE. There are four types of logging, depending on which part of the JAP client is outputting the log: GUI, NET, THREAD and MISC. The constants can be added to each other if the output is relevant to more than one part of the JAP client.

The global log setting DETAIL\_LEVEL also determines the level of logging detail. On the highest setting, the class, method and even the line of code from which the logging message was sent will be output. Therefore, localization information (classes or method names) in the log message does not make sense and is not allowed.


\bigskip

\subsubsection{Mixproxy}
Log outputs occur through a method in the CAMsg class:

\ \ \ \ CAMsg::printMsg(UINT32 type, char* message)

The following log types are available as macros in CAMsg: LOG\_DEBUG, LOG\_INFO, LOG\_CRIT, LOG\_ERR. Only the outputs whose log level is equal to or higher than the configured log level will be written to the log file.

\clearpage\subsection{XML (Java)}

\bigskip

The class anon.util.XMLUtil must be used for XML operations if possible. Objects that can be manipulated in XML must implement the anon.util.IXMLEncodable interface and should also contain the static attribute

\ \ public static final String XML\_ELEMENT\_NAME

which contains that name of the XML element created.


\bigskip


\bigskip

\subsection{Images (JAP/MixConfig)}

\bigskip

Pictures and graphics are centrally located in the images directory. If graphics with only 16 colors exist, they are placed in the lowcolor subdirectory. The filename can then be entered in the JAPConstants class and the graphic can be loaded using the 

\ \ \ \ \ \ GUIUtils.loadImageIcon(String strImage, boolean sync) 

\ \ \ \ \ \ GUIUtils.loadImageIcon(String strImage) 

methods.


\bigskip


\bigskip

\subsection{Other Resources (JAP/InfoService/MixConfig)}

\bigskip

Other resources (texts, binary data, URLs, ...) can be loaded by methods of the

anon.util.ResourceLoader class.


\bigskip


\bigskip

\subsection{External Libraries}

\bigskip

External libraries are programs or source code packages that do not originate from the AN.ON developer community. New external libraries may only be used after prior arrangements with the central AN.ON management. Furthermore, {\textquotedbl}exotic{\textquotedbl} libraries that only run on certain platforms may not be used. Code that excludes commercial use, GPL for example, are also not permitted.


\bigskip

\subsubsection{JAP/InfoService/MixConfig}
The source code is compiled with Java version 1.1.8\_010. Libraries, classes and methods from newer Java versions are thus not allowed.


\bigskip

\subsubsection{Mixproxy}
The STL (Standard Template Library) may not be used. Of course, other proprietary libraries (for example MFC) are also not permitted.


\bigskip

\clearpage\section{Naming Conventions}
\label{bkm:Namenskonventionen}
\bigskip

The naming conventions presented here apply to all labels such as constants, attributes, etc. The labels may have to be supplemented with prefixes. All labels should clearly indicate their purpose. This topic is covered by the subchapters that follow.


\bigskip

\subsection{Constants}

\bigskip

Constants are capitalized. Multiple words are connected by underscores.

Example:

\ \ final int SPECIAL\_INT\_CONSTANT = 0x34; \ // Java

\ \ const SINT32 MY\_INT\_CONSTANT = 0x34; \ // C++ 


\bigskip


\bigskip

\subsection{Variables}

\bigskip

Each variable must be named according to the following schema:

\ \ {\textless}prefix{\textgreater}\_{\textless}type{\textgreater}Name

Variable names must contain information about their scopes. \ Thus, a prefix is added to each variable name according to the following table:


\bigskip

\begin{flushleft}
\tablefirsthead{}
\tablehead{}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{m{5.249cm}|m{1.285cm}m{9.842cm}}
Variable Scope &
Prefix &
Declaration\\\hline
Local \ Variable &
~
 &
within a method\\
Member Variable &
m &
within a class\\
Static member Variable &
ms &
within a class, static Attribute\\
Argument &
a &
argument for a method\\
Return value &
r &
argument for a method, used as a return value\\
\end{supertabular}
\end{flushleft}

\bigskip

In addition to scope, the variable type must be integrated into the name. In most cases the programmer can freely choose the label. The following data types are an exception:


\bigskip


\bigskip

\begin{flushleft}
\tablefirsthead{Variable Type &
Type Label\\}
\tablehead{Variable Type &
Type Label\\}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{m{5.282cm}|m{3.919cm}}
\hline
bool, boolean &
b\\
char*, string, String &
str\\
\end{supertabular}
\end{flushleft}

\bigskip

Elementary types (numbers) do not need a type label. The type label can also be left off if the name length becomes long and unwieldy (for example, \ m\_JapClientWindowEventHandlerTemp). Examples for correct naming:

\ \ private static String ms\_strName;


\bigskip

C++: the symbol for reference types (\&) and pointers (*) is always directly after the type, not by the variable name. Example: char* m\_strName = {\textquotedbl}Caesar{\textquotedbl};


\bigskip

\subsection[Methods]{Methods}

\bigskip

A method name or function name consists of alphabet symbols where the first symbol is a small letter. The first word describes the functionality in the form of a verb. Words are separated by always capitalizing the first letter of each word (with the exception of the leading verb). It should be recognizable from the name whether the method is one that makes changes or one that does not make changes. For example, getNextAndIncrement() is easily recognizable as a method that alters values. On the other hand, one expects that the method getTheMix() does not change the object.


\bigskip


\bigskip

\subsection{Classes / Interfaces}

\bigskip

Class names consist of one or more words written together where each word must begin with a capital letter, for example, JapCascadeMonitorView. The name of a class should indicate an object (for example CASocket) or a handler (for example, CAListCellRenderer) and should describe the actual function of the class.

Abstract classes get the prefix Abstract, for example, AbstractConnection.


\bigskip

\subsubsection{Java}
Interfaces have the {\textquotedbl}I{\textquotedbl} prefix, for example, IConnection. The name should normally indicate a property, for example, IDistributable.


\bigskip

\subsubsection{C++}
All class names related directly to the Mixproxy must begin with CA.


\bigskip


\bigskip

\subsection{Message Properties (JAP/MixConfig)}

\bigskip

Message properties are always named after the class where they are defined:

\ \ \ \ \ \ packagename.classname\_messageLabel = ...

Each property must be defined in one and only one class as a constant defined like this:


\bigskip

\ \ \ \ \ \ static final String MSG\_LABEL = ClassName.class.getName() + “\_messageLabel”;

The message label must not contain other characters than ASCII letters and starts with a lowercase letter. If it consists of more than one word, the words are separated by writing \ each first letter uppercase. The constant name always starts with “MSG\_”.


\bigskip

If a property is used in many classes of a package, it is either placed in the class it logically belongs to, or, if this is not clear, in a common class named “Messages”.


\bigskip

Messages are then loaded, for example, by writing


\bigskip

\ \ \ \ \ \ \ \ \ String strMessage = JAPMessages.getString(MSG\_LABEL);


\bigskip

Messages that are not defined in any class may be deleted.


\bigskip


\bigskip

\subsection[Image File Names (JAP/MixConfig)]{Image File Names (JAP/MixConfig)}

\bigskip

The naming convention for images corresponds to the one of the message properties:


\bigskip

\ \ \ \ \ \ \ \ static final String IMG\_LABEL = ClassName.class.getName() + “\_imageLabel”;


\bigskip

The differences are that an image file contants starts with „IMG\_“ and, if there is no logically best class to place it, it has to be defined in a class named „Images“.


\bigskip

Images are then loaded, for example, by writing


\bigskip

\ \ \ \ \ \ \ ImageIcon icon = GUIUtils.loadImageIcon(IMG\_LABEL);


\bigskip

Images that are not defined in any class may be deleted.


\bigskip


\bigskip

\subsection{Test Classes}

\bigskip

The test class names should indicate the name of the tested class or module with {\textquotedbl}Test{\textquotedbl} added to the end, for example, CAMsgTest for the CAMsg class.


\bigskip


\bigskip

\subsection{Class File Name Extensions}

\bigskip

C++ header files always end in .hpp and the implementation of the class is always found in the respective .cpp file. The extension .java is always used for Java files.

Only one class definition is allowed per file. The class name must be the same as the file name without the file name extension. 

\clearpage\section{Type Conventions}
\label{bkm:Typkonventionen}
\bigskip

\subsection{Simple Data Types (C++)}

\bigskip

To achieve platform independence for elementary data types, only the following data types are used:


\bigskip

\begin{center}
\tablefirsthead{\hline
\centering Data Type  &
\centering Bytes &
\centering\arraybslash Value Range\\}
\tablehead{\hline
\centering Data Type  &
\centering Bytes &
\centering\arraybslash Value Range\\}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{|m{2.155cm}|m{1.742cm}|m{9.217cm}|}
\hline
SINT8 &
\centering 1 &
{}-128..127 or all ASCII symbols up to 127\\\hline
UINT8 &
\centering 1 &
0..255 or all ASCII symbols\\\hline
SINT16 &
\centering 2 &
{}-32768..32767\\\hline
UINT16 &
\centering 2 &
0..65535\\\hline
SINT32 &
\centering 4 &
{}-2147483648.. 2147483647\\\hline
UINT32 &
\centering 4 &
0..4294967295\\\hline
UINT64 &
\centering 8 &
0..18446744073709551615 {\textgreater} 1019\\\hline
float &
\centering 4 &
{}-1038..1038\\\hline
double &
\centering 8 &
{}-10308..10308\\\hline
\end{supertabular}
\end{center}

\bigskip

The special forms, SINT and UINT, reflect either the 16- or 32- versions and should never be used due to platform dependence!


\bigskip


\bigskip

\subsection{Constants (Java)}

\bigskip

It should be noted that constant object references defined with final in Java only make the reference constant. The object itself can still be altered. To duplicate const behavior (from C++) in Java, an Immutable{\textless}Classname{\textgreater} interface must be created for each class. The interface contains only the non-changing methods that for this class. A constant object can then be created as follows, for example:

\ \ final ImmutableMyClass A = new MyClass();

This object is thus a true constant, since the public attribute is not allowed (see below).


\bigskip


\bigskip

\subsection{Variables}

\bigskip

Variables on the class level (member and static variables) must always be declared private. public and protected are not permitted except for constants. Access to these variables should always proceed through get/set{\textless}variable name without prefix{\textgreater} methods, for example, getName() for the attribute m\_strName. Constants that are also allowed to be accessed directly are an exception to the rule. For boolean attributes, the reading method is is{\textless}variable name without prefix and without b{\textgreater}, for example isReady() for the attribute bool m\_bReady.

\clearpage\subsection{Methods}

\bigskip

Arguments that can be given as references (C++: type\&, type*; Java: every object) and are not allowed to be changed by the method must be declared as constant arguments if possible.


\bigskip

C++: Methods that do not change the state of their own objects must be defined as const.


\bigskip


\bigskip

\subsection{Classes / Interfaces}

\bigskip

\subsubsection{Static Code}
Static code should be avoided in classes, since it generally weakens the object orientation and clarity of the code structure.


\bigskip

\subsubsection{Singletons}
Classes with a singleton design patter should only be implemented if absolutely necessary, since code dependent on this class is usually not testable or is testable only with extreme difficulty (through Unittests). Furthermore, singletons make flexibility or swapping of code more difficult and generally weaken the object oriented structure of the code.


\bigskip

\subsubsection{{\textquotedbl}final{\textquotedbl} Classes (Java)}
Classes should always be declared final by default in order to improve performance. If a class needs to be inheritable later, the final attribute can then be removed.


\bigskip

\subsubsection{Templates (C++)}
Templates are not allowed for compatibility reasons.


\bigskip


\bigskip

\subsection{Threads}

\bigskip

All classes and structures that are simultaneously used by more than one thread must be implemented thread safe. To create thread safe code, you absolutely must consult current literature because this issue is not trivial!


\bigskip

\subsubsection{Java}
The Runnable interface must be implemented for threads. Inheriting from Thread is not allowed because it can lead to faulty behavior in some JVMs. The keyword synchronized must be used to ensure thread safety.


\bigskip

Thread.interrupt() works only under certain conditions. In particular, you must be sure that Thread.isInterrupted() is tested for in the thread's loops and that I/O operations contain a timeout or other similar possibility of interrupting a thread. Otherwise it depends on the JVM whether a thread can be ended or not.


\bigskip

\subsubsection{C++}
The CAThread class is used for instantiating a thread. Thread safety can be achieved by using the lock() and unlock() methods of objects from the CAMutex class.


\bigskip


\bigskip

\subsection{Exceptions}

\bigskip

\subsubsection{Java}
When exceptions are thrown, they should specify the error as precisely as possible. Whenever possible, no new exceptions should be defined unless they offer real functionality.


\bigskip

\subsubsection{C++}
C++ exceptions are not allowed due to compatibility issues. Instead, each method must return a value of SINT32 type, which represents an error code. If no error occurs, the constant E\_SUCCESS is returned.


\bigskip

The error codes are defined in StdAfx.h and new error codes can be added as necessary. However, new error codes should only be added upon arrangement with the central code management.


\bigskip

The actual return values of a method are generally returned using a pointer or reference in the method arguments. For example:


\bigskip

\ \ SINT32 doSomething(UINT32 a\_u32Value, Object\& r\_Object)


\bigskip

A return value other than SINT32 will be tolerated if necessary for trivial methods (for example, get and set methods).


\bigskip


\bigskip

\subsection{HTML-Formated GUI Elements (JAP/MixConfig)}

\bigskip

Some GUI elements (labels, buttons, etc.) can be formatted with the help of HTML tags. When this is done, all tags are to be written in lower case and without spaces, for example:


\bigskip

\begin{verbatim}
JLabel label=new Jlabel("<html><body><b>A test in bold...</b></body></html>");
\end{verbatim}
Otherwise it can not be guaranteed that every JDK will correctly display the formatting.

\clearpage\section{Documentation}
\label{bkm:Dokumentation}
\bigskip

\subsection{Documentation Tool}

\bigskip

Javadoc is the minimum documentation standard. Javadoc allows the creation of HTML-based documentation based on the source code. However, Doxygen is used for documentation creation because it posses further functionality and also supports Javadocs under C++ [DOXYGEN].


\bigskip


\bigskip

\subsection{Procedure}

\bigskip

The documentation for classes and methods should always be written before the actual implementation. Based on experience, little is documented otherwise. When the code is changed, the documentation must also be changed (before the code is changed if possible). Note: In C++, the documentation for classes, attributes, and member functions must appear only in the header files.

Multi-line comments must be written directly before the code to be documented as follows:

\ \ /** 

\ \ * ....(comments)

\ \ * @tag ....(comments)

\ \ */

One or more so-called tags, which implement special functions, may appear within the comments preceded by an @.


\bigskip

A single-line comment must also be written directly before the code to be documented as follows:

\ \ /// ....(comments)


\bigskip

The documentation language is English (UK).


\bigskip


\bigskip

\subsection{Classes }

\bigskip

The class and interface descriptions should describe the purpose of the class or interface. If a short example is needed for clarity, it can be included as part of the description.


\bigskip


\bigskip

\subsection{Attribute (@param Tag)}

\bigskip

Only attributes whose function is not recognizable by their names need to be documented. Attributes are to be described within the comments of the method using the @param tag: @param attribute-name description


\bigskip


\bigskip


\bigskip


\bigskip

\subsection[Return Values (@return Tag)]{Return Values (@return Tag)}

\bigskip

Return values are to be described within the comments of the method using the @return tag: @return description


\bigskip


\bigskip

\subsection{Methods}

\bigskip

The functionality, input parameters, and if necessary the result are to be documented for methods. Furthermore, exceptions and errors must be documented including when they could occur and which values they could return.

Units (for example, whole number percentages) and allowed value ranges must also be commented.


\bigskip

Note:

If several methods interact with each other within a class, it may be advantageous to explain the interactions once in the class/interface documentation and then only describe the actual purpose of the method for the method description itself. If this is done, @see must be used to link the corresponding class and method documentation together:

\ \ @see myClass()

\ \ @see myMethod() \ \ (arguments must not be given here.)

Tip:

When implementing interface methods or overwriting methods, the documentation does not need to be repeated. Special cases can be documented if desired. Here too, an @see tag must indicate the implemented interface, for example: @see java.lang.Comparable.method().


\bigskip


\bigskip

\subsection{Algorithms}

\bigskip

The code within methods, from here on referred to as an algorithm, must also be commented unless it is trivial (for example, if it is only a value being assigned). However, each individual line should not be commented, rather whole code blocks. The comments are not a repeat of the code.

When algorithms are taken from external sources (for example, an implementation of quicksort), the source of the algorithm must also be given in the comment.

If an algorithm requires very detailed comments, consideration should be taken whether the algorithm can be simplified so that it is more easily understood. Experience shows that someone will eventually bring the code into a {\textquotedbl}clean{\textquotedbl} form, but adjusting the comments is often forgotten! Furthermore, {\textquotedbl}hacks{\textquotedbl}, {\textquotedbl}fixes{\textquotedbl} and similar are generally not tolerated.


\bigskip


\bigskip

\subsection{@todo Tag}

\bigskip

Generally there are things in source code yet to be done, that have been put off for a later date. These areas should be marked with an @todo tag so that they are also visible in the javadoc documentation: /** @todo reason */


\bigskip

\clearpage\section{Other Conventions}
\label{bkm:SonstigeKonventionen}
\bigskip

\subsection{Code Style}

\bigskip

Die folgenden Codestyle-Regeln können normalerweise von der IDE automatisch auf den Code angewandt werden [ENTWUMG]. Dennoch sollte jeder Programmierer sie berücksichtigen.


\bigskip

\subsubsection{Line Length}
Die maximale Länge von Programmzeilen beträgt 110 Zeichen. Dadurch ist gewährleistet, dass die Seiten auch auf kleinen Bildschirmen gut darstellbar und noch gut zu drucken sind, was beispielsweise für Code-Review etc. notwendig ist. Abweichungen sind nur zulässig, wenn aufgrund der Übersichtlichkeit des Quelltextes mehr Zeichen erforderlich sind. Ein Beispiel dafür wäre die matrixähnliche Anordnung von Code bei der Definition eines Zustandsgraphen oder Konfigurationen einer Maske.

Wenn die Liste der Funktionsargumente zu lang für eine Zeile ist, wird sie am Zeilenende umgebrochen und in der nächsten Zeile weitergeschrieben. Diese Zeile sollte um mindestens zwei Tabulatoren eingerückt werden. Sind weitere Zeilen nötig, so liegen diese auf der gleichen Höhe.


\bigskip

\subsubsection{Tab Size}
Die Einrücktiefe bei Verschachtelungen beträgt 4 Leerzeichen, bzw. einen Tabulator. Es werden grundsätzlich Tabulatoren zur Einrückung verwendet.


\bigskip

\subsubsection{Brace Setting}
Öffnende geschweifte Klammern stehen durch ein Leerzeichen getrennt direkt unter dem auslösenden Code und auf der gleichen Einrücktiefe. Schließende geschweifte Klammern stehen in einer eigenen Zeile ebenfalls auf der gleichen Einrücktiefe wie der auslösende Code. Die Anweisungen innerhalb der Klammern sind einmal eingerückt. Auf Höhe der Klammern stehen keine Anweisungen.


\bigskip

Beispiel:


\bigskip

\ \ public String getName() 

\ \ \{

\ \ \ \ return m\_strName;

\ \ \}


\bigskip

Öffnende runde Klammern stehen bei Methoden direkt hinter dem auslösenden Code, schließende runde Klammern direkt hinter dem eingeschlossenen Code. Bei Schlüsselwörtern sind die runden Klammern durch ein Leerzeichen vom Schlüsselwort getrennt.


\bigskip

Beispiele:

\ \ setGlobals(aParam1, aParam2, aParam3);

\ \ while (myObject != enumeration.next()); 


\bigskip

\subsubsection{Methodenparameter}
Kommas stehen direkt hinter Methodenparametern. Zum nächsten Parameter wird jeweils ein Abstand von einem Leerzeichen gelassen (Beispiel siehe oben).

\subsection[Coding Conventions]{Coding Conventions}
\label{bkm:Codierungskonvetionen}
\bigskip

\begin{itemize}
\item Pro Zeile darf aus Gründen der Übersichtlichkeit nur ein Statement kodiert werden. Ausnahme ist die Deklaration von Bedingungen für for{}-Schleifen, die in einer Zeile geschrieben werden darf.
\end{itemize}
\begin{itemize}
\item Es sollte nur ein return pro Methode verwendet werden. Weitere return-Anweisungen sind zulässig, wenn am Anfang einer Methode die Vorbedingungen abgeprüft werden, bzw. wenn der Code sonst sehr unübersichtlich würde.
\end{itemize}
\begin{itemize}
\item Der ?:-Operator sollte nicht verwendet werden, da er das Debuggen unnötig erschwert.
\end{itemize}
\begin{itemize}
\item Grundsätzlich sollten möglichst wenige Objekte erzeugt werden, um die Performance nicht unnötig zu drücken.
\item Konstanten sollen nie in Form von konkreten Zahlenwerten bzw. expliziten Characterstrings angegeben werden, sondern immer über den „Umweg“ einer Klassenvariable. Dies erleichtert eine spätere Umbenennung enorm und vermeidet Tippfehler.
\item If(...){}-chains with only one possible condition must be written as if()... else if()... or as switch() statement (but may not be written as consecutive if...if...if...) 
\item Boolean values in if{}-statements must be written as if(boolean) but not as if(boolean == true{\textbar}false)
\end{itemize}

\bigskip

\subsubsection{Java}
\begin{itemize}
\item Statt der Stringverkettung mit „+“ sollte in häufig durchlaufenen Schleifen ein anon.util.MyStringBuilder verwendet und mit der append(..) – Methode aufgebaut werden. Dadurch wird die Performance im Allgemeinen gesteigert.
\end{itemize}
\begin{itemize}
\item Referenzen auf Objekte, die nicht mehr benötigt werden, sollten sofort gelöscht werden, um dem Garbage Collector die Möglichkeit zu geben, den Speicher aufzuräumen (objct = null). Dies ist mit finalize() nicht sichergestellt, weshalb finalize() nicht verwendet werden darf. 
\item Be warned when using Enumerations: In case a second thread alters the number or the order of elements in the instance that generated the Enumeration, the Enumeration is not updated! This means, for example, if you remove an element from a Vector, the Enumeration skips the next element or may even throw an Exception if there is none. The solution is to synchronize on the object whenever there is the possibility of competing threads.
\item Manipulation of GUI elements is only allowed in the AWT event thread. Otherwise, it might have no effect on the GUI. To test if your code is executed in the event thread, call SwingUtilities.isEventDispatcherThread(). If the code is not executed in the event thread, you may use SwingUtilites.invokeLater() or SwingUtilities.invokeAndWait() to manupulate the GUI. On the other hand, no time-consuming code may be executed in the event thread, as this would block the GUI.
\item If you need to put manual breaks into HTML labels like JLabel, use {\textless}p{\textgreater} instead of {\textless}br{\textgreater}, as Java 1.1 ignores {\textless}br{\textgreater} when computing the preferred width.
\end{itemize}

\bigskip

\subsubsection{C++}
\begin{itemize}
\item Grundsätzlich sollten eher dynamisch allokierte, das heißt über new instanzierte, Objekte verwendet werden als per Typdefinition instanzierte. Dies stellt sicher, dass das neu erzeugte Objekt so im Speicher ausgerichtet wird, wie es für die jeweilige Zielplattform aus Performancesicht am Günstigsten ist.
\end{itemize}
\begin{itemize}
\item RTTIs (Run Time Type Informations) dürfen aus Kompatibilitätsgründen nicht verwendet werden, sollten also bereits im Compiler abgeschaltet werden.
\end{itemize}
\begin{itemize}
\item Dynamisch angelegte, nicht mehr gebrauchte Zeiger auf Objekte sollten sofort gelöscht werden, da es keine Garbage Collection gibt und der Speicher nicht von selbst freigegebenen wird.
\end{itemize}
\clearpage\section{Testing}
\label{bkm:Testen}
\bigskip

\subsection{Introduction to Unittests}

\bigskip

Um die Funktionalität der Software sicherstellen zu können, sind als qualitätssichernde Maßnahmen Entwickler- bzw. Modultests und Integrationstests durchzuführen. Außerdem werden Lasttests benötigt, um die Performance-Anforderungen an die Software zu überprüfen. 


\bigskip

Teile dieser Tests sind automatisierbar: nämlich die auf Modulebene, auch Unittests genannt. Ein Modul kann dabei eine einzelne Methode, Klasse, Package oder auch das Zusammenspiel mehrerer dieser Module sein. \ Bevor ein Entwickler eine neue Version seines Moduls veröffentlicht, d.h. unter die Versionskontrolle stellt, sollte dieses in Form eines Modultests getestet werden. Im Rahmen der Integrationstests, die sämtliche Testfälle umfassen, wird dann sichergestellt, dass der aktuelle Stand der freigegebenen Module fehlerfrei zusammenspielt. 


\bigskip

Die Modultests liegen in Form von sogenannten Testsuiten vor, die sich meist auf eine konkrete, zu testende Klasse beziehen und mehrere Testfälle auf die Methoden der Klasse zusammenfassen. Jeder Testfall bzw. Testcase enthält ein oder mehrere Tests. Hier werden, ähnlich dem bekannten ASSERT Makro, Bedingungen auf Gültigkeit geprüft. Die Tests liegen normalerweise in einem vom Produktivcode getrennten Verzeichnis „test“. \ Der Produktivcode muss völlig unabhängig von den Testfällen sein.


\bigskip

Es sollte mindestens ein Testfall pro Methode vor deren eigentlicher Implementierung (!) geschrieben werden. Pro Klasse sollte mindestens eine Testsuite angelegt werden. Auch für das Zusammenspiel von mehreren Methoden und Klassen können eigene Testsuites erforderlich sein. Während der Entwicklung können mit neuen Anforderungen auch neue Testfälle hinzukommen.


\bigskip

Das Konzept der Unittests wurde ursprünglich von Kent Beck und Erich Gamma im Rahmen des Extreme Programming entwickelt. Für die Durchführung von Unittests existieren frei verfügbare Open-Source Bibliotheken. Wir verwenden für Java JUnit [JUNIT] von Kent Beck und Erich Gamma bzw. für C++ CppUnit [CPPUNIT] von Sourceforge.net. Über dieses Dokument hinausgehende Hilfe zu Unittests bzw. JUnit findet man beispielsweise unter [UNITTESTS]. Weiterführende Informationen zum Testen objektorientierter Software findet man unter [OOTESTEN]. \ 


\bigskip

Die Modultests sind für neue Klassen verpflichtend, soweit sie technisch möglich sind.


\bigskip


\bigskip

\clearpage\subsection{JUnit}

\bigskip

\subsubsection{General Information on JUnit}
JUnit basiert auf Testfällen, die durch die Klasse TestCase gruppiert werden. Mehrere Gruppen von Testfällen können im Kontext einer TestSuite abgearbeitet werden. Beide Klassen implementieren das Interface Test.

Um JUnit verwenden zu können, muss jeweils junitx.framework.PrivateTestCase importiert werden. Für JAP/InfoService wird die Klasse \ junitx.framework.extension.XtendedPrivateTestCase vorgeschrieben.


\bigskip

\subsubsection{Test Classes}
Jede Testklasse ist von PrivateTestCase bzw. XtendedPrivateTestCase abgeleitet. Sie sollte in einem Verzeichnis Packagename.test liegen und sich auf eine konkrete, zu testende Klasse im Package Packagename beziehen. Ihr Name setzt sich aus dem Namen der zu testenden Klasse plus \ Test zusammen (ClassnameTest). Sie kann folgende Methoden enthalten:

\ \ public void setUp()\ \ \ \ \ \ wird vor jedem Test ausgeführt

\ \ public void tearDown()\ \ \ \ wird nach jedem Test ausgeführt

\ \ public void testX()\ \ \ \ \ \ ein oder mehrere Testfälle

Der (einzige) Konstruktor sollte einen String name als Argument haben und selber super(name) aufrufen.


\bigskip

\subsubsection{Test Cases }
Die Methodennamen von Testfällen müssen immer mit dem Präfix test beginnen und die folgende Signatur haben:

\ \ \ \ public void test{\textless}Testfallbezeichnung{\textgreater}()

Dies ist notwendig, damit die Testfälle automatisch über den Java-Reflection-Mechanismus gestartet werden können.

In den Implementierungen der Testfälle können die Tests über assert{}-Funktionen der TestCase{}-Klasse ausgeführt werden, z.B. TestCase.assertTrue oder TestCase.assertEquals. Schlägt eine assert{}-Annahme fehl, wird dies mitprotokolliert.


\bigskip

\subsubsection{TestSuite}
Im Rahmen einer TestSuite werden beliebig viele TestCase ausgeführt und ausgewertet. JUnit bietet verschiedene Umgebungen, in denen die Tests abgearbeitet und ausgewertet werden können. Wir verwenden den junit.swingui.TestRunner. 

Dabei geht man wie folgt vor:

\begin{itemize}
\item Erzeuge im Verzeichnis Packagename.test (wenn das zu testende Modul im Package Packagename liegt) eine Klasse mit der Bezeichnung Alltests.
\item Implementiere eine Methode static Test suite(), welche ein TestSuite Objekt erzeugt (mit dem Konstruktorparameter „Packagename“), diesem Objekt alle Testfallklassen für das zu testende Paket mittels der Methode addTestSuite({\textless}Testklassenname{\textgreater}.class) und alle Suiten der Unterpackages mittels der Methode addTest(Packagename.AllTests.suite()) hinzufügt und es schließlich an den Aufrufer zurückgibt. 
\item Implementiere eine main{}-Methode, welche die Tests mittels der Methode \newline
junit.swingui.TestRunner.run(AllTests.class) \newline
durchführt.
\end{itemize}
Sämtliche Unittests im AN.ON-Projekt befinden sich in einem gesonderten Verzeichnis test. Die Packages in diesem Verzeichnis korrespondieren zu denen im Produktivcode. In den Verzeichnissen des Produktivcodes dürfen keine Testfälle abgelegt werden.


\bigskip

\subsubsection{Testing Private, Protected and Package-scoped Members}
Das Testen von private, protected und package scoped Members (im Folgenden allgemein als private Members bezeichnet) ist über das Framework JUnitX möglich [JUNITX]. 


\bigskip

Ein Aufruf der Methode myMethod eines Objektes der Klasse {\textless}TestedClass{\textgreater} und die anschließende Prüfung der privaten Variable m\_value erfolgt beispielsweise so:

Object m\_{\textless}TestedClass{\textgreater}Object = newInstance({\textquotedbl}packagename.{\textless}TestedClass{\textgreater}{\textquotedbl}, NOARGS);

Object result = invokeWithKey(m\_{\textless}TestedClass{\textgreater}Object, {\textquotedbl}myMethod{\textquotedbl}, NOARGS);

assertEquals(asBoolean(result), true);

assertEquals(getInt(m\_{\textless}TestedClass{\textgreater}Object, {\textquotedbl}m\_value“), 1);


\bigskip

Im Paket junitx.framework.extension werden Hilfsklassen bereitgestellt, die speziell \ das Testen privater Members nochmals vereinfachen:


\bigskip

junitx.framework.extension.TestProxy:

In jedem Package, in dem sich zu testende Klassen mit private Members befinden, muss eine Klasse mit exakt diesem Namen (TestProxy) von TestProxy abgeleitet und in das Verzeichnis test/packagename kopiert werden. Dabei darf diese Klasse nur folgende Zeilen als Inhalt haben (wobei packagename natürlich angepasst werden muss):

package packagename;


\bigskip

import java.lang.reflect.*;


\bigskip

public class TestProxy extends junitx.framework.extension.TestProxy \{


\bigskip

\ \ \ protected Object createInstance(Constructor a\_Constructor, Object[] a\_args) 

\ \ \ \ \ \ throws Exception

\ \ \ \{

\ \ \ \ \ \ return a\_Constructor.newInstance(a\_args);

\ \ \ \}

\}

Da die Klasse TestProxy nirgendwo direkt verwendet wird muss, damit der TestProxy auch automatisch kompiliert wird, mindestens eine Referenz auf diese Klasse in einer anderen Klasse angelegt werden. Dazu bietet sich die Klasse AllTests im jeweiligen Unterpackage test an. In die Klasse AllTests sollten folgende Zeilen aufgenommen werden:

...

import java.lang.reflect.*;

...

TestProxy m\_proxy;

\clearpage\subsection{CppUnit}

\bigskip

\subsubsection{General Information on CppUnit}
CppUnit ist ähnlich aufgebaut wie JUnit und basiert auf der Klasse TestFixture, die einzelne Testfälle zusammenfasst. Um CppUnit komfortabel verwenden zu können, müssen folgende includes gesetzt werden:

\ \ \ \ \#include {\textless}cppunit/extensions/HelperMacros.h{\textgreater}

\ \ \ \ \#include {\textless}cppunit/TestFixture.h{\textgreater}


\bigskip


\bigskip

\subsubsection{Test Classes}
Jede Testklasse ist von CppUnit::TestFixture abgeleitet und sollte sich auf eine konkrete, zu testende Klasse beziehen. Sie kann folgende (public) Methoden enthalten:

\ \ void setUp()\ \ \ \ \ \ wird vor jedem Test ausgeführt

\ \ void tearDown()\ \ \ \ wird nach jedem Test ausgeführt

\ \ void testX()\ \ \ \ \ \ ein oder mehrere Testfälle, beschrieben durch X

Nach den Methoden sollte immer folgendes Makro folgen, damit die Tests auch ausgeführt werden können:

\ \ CPPUNIT\_TEST\_SUITE(ClassnameTest);

\ \ CPPUNIT\_TEST(testX);

\ \ CPPUNIT\_TEST(testY);

\ \ ...

\ \ CPPUNIT\_TEST\_SUITE\_END(); \ 

Dabei muss ClassnameTest dem Namen des TestCases entsprechen, und testX, testY, ... dem Namen der zu testenden Testfälle.


\bigskip


\bigskip

\subsubsection{Test Cases}
Die Methodennamen von Testfällen sollten immer mit dem Präfix test beginnen und die folgende Signatur haben:

\ \ \ \ public void test{\textless}Testfallbezeichnung{\textgreater}()

Die Tests können über Makros durchgeführt werden. Das am Häufigsten verwendete Makro ist 

\ \ \ \ CPPUNIT\_ASSERT\_EQUAL(expected, result);

wobei expected und result den == Operator zum Vergleich und den {\textless}{\textless} Operator zur Ausgabe überschrieben haben müssen.

Analog kann mit dem Makro

\ \ \ \ CPPUNIT\_ASSERT(expression);

der Wahrheitswert eines boolschen Ausdrucks ermittelt werden.

Durch Anhängen von MESSAGE kann im Fehlerfall eine zusätzliche Ausgabe erzeugt werden, wobei message eine Zeichenkette sein muss:

\ \ \ \ CPPUNIT\_ASSERT\_EQUAL\_MESSAGE(message, expected, result);

\ \ \ \ CPPUNIT\_ASSERT\_MESSAGE(message, expression);


\bigskip


\bigskip


\bigskip

\subsubsection[TestSuite]{TestSuite}
Die Tests können in mehrere Packages (TestSuites) aufgeteilt werden. Dazu ist für jedes Package eine Klasse AllTests{\textless}Packagename{\textgreater} anzulegen, die sämtliche Testklassen ausführt, und eine Oberklasse AllTests, die alle anderen AllTests{\textless}...{\textgreater} ausführt.

Auch AllTests ist von \ CppUnit::TestFixture abgeleitet und enthält eine nur folgende Methode:

\ \ \ \ static CppUnit::Test* suite()

In dieser Methode befinden sich folgende Aufrufe:

\ \ \ \ CppUnit::TestSuite* suiteOfTests = new CppUnit::TestSuite( {\textquotedbl}AllTests{\textless}...{\textgreater}{\textquotedbl} );

\ \ \ \ suiteOfTests-{\textgreater}addTest( DummyClass1Test::suite() );

\ \ \ \ suiteOfTests-{\textgreater}addTest( DummyClass2Test::suite() );

\ \ \ \ ...

In der ersten Zeile definiert sich die Klasse selbst; es muss exakt der Klassenname eingetragen werden. Die nächsten Zeilen sind die Testklassen, die im Rahmen dieser Suite ausgeführt werden sollen.


\bigskip


\bigskip

\subsubsection{Testing Private and Protected Members}
Sollen private oder protected Memberfunktionen einer Klasse getestet werden, so müssen die Testklassen in der zu testenden Klasse als friend deklariert werden. 


\bigskip


\bigskip

\subsection{Dummy and Mock Objects}

\bigskip

Manchmal müssen Methoden oder Objekte getestet werden, die wiederum ein oder mehrere Objekte als Argument benötigen. Um den Test nicht unnötig zu verkomplizieren oder auch um ihn überhaupt erst möglich zu machen entwirft man speziell für diesen Zweck sogenannte Dummy-Objekte. Diese sind von der Klasse \ der „richtigen“ Argument-Objekte abgeleitet, besitzen aber keine wirkliche Funktionalität. Eine gute Beschreibung, wie man solche Dummy-Objekte geschickt implementiert, findet man hier:


\bigskip

\ \ http://www.dpunkt.de/leseproben/3-89864-150-3/Kapitel\_6.pdf


\bigskip


\bigskip

\clearpage\section{Literature Cited}

\bigskip

\begin{flushleft}
\tablefirsthead{\hline
Textreferenz &
Titel\\}
\tablehead{\hline
Textreferenz &
Titel\\}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{|m{3.106cm}|m{13.759cm}|}
\hline
[CODING STANDARDS] &
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

~
\\\hline
\label{bkm:CPPUNIT}[CPPUNIT] &
http://cppunit.sourceforge.net\\\hline
\label{bkm:DOXYGEN}[DOXYGEN] &
http://www.doxygen.org\\\hline
\label{bkm:ENTWUMG}[ENTWUMG] &
Entwicklungsumgebung.pdf\\\hline
\label{bkm:JUNIT}[JUNIT] &
http://www.junit.org\\\hline
\label{bkm:JUNITX}[JUNITX] &
http://www.extreme-java.de\\\hline
\label{bkm:OOTESTEN}[OOTESTEN] &
Uwe Vigenschow: Objektorientiertes Testen und Testautomatisierung in der Praxis, dpunkt.verlag, 1.Auflage 2005

http://www.oo-testen.de\\\hline
\label{bkm:UNITTESTS}[UNITTESTS] &
Johannes Link: Unit Tests mit Java, dpunkt.verlag, 1.Auflage 2002

http://www.dpunkt.de/utmj/\\\hline
\end{supertabular}
\end{flushleft}

\bigskip


\bigskip

\clearpage\section{Appendix (Summary)}

\bigskip

P 

\begin{itemize}
\item Sicherheit
\item Kompatibilität
\item Performance
\item Qualität
\end{itemize}

\bigskip

S

Zum genauen Aufbau von Klassen und Methoden siehe Kapitel \ref{bkm:Struktur}.


\bigskip

L

\begin{itemize}
\item Zur Textdefinition-und Ausgabe die Klasse JAPMessages benutzen.
\item Bilder laden: JAPUtil.loadImageIcon(String strImage, boolean sync)
\item JAP: \ \ Logging über logging.LogHolder.log(level, type, message)
\item Mix: \ \ Logging über CAMsg::printMsg(UINT32 typ, char* format)
\item XML (Java): die Klasse anon.util.XMLUtil \ verwenden
\item Keine proprietären Bibliotheken / keine STL verwenden
\end{itemize}

\bigskip

N 

\begin{itemize}
\item Konstanten nur mit Großbuchstaben: const int SPECIAL\_INT\_CONSTANT;
\item Variablen nach dem Schema: {\textless}Präfix{\textgreater}\_{\textless}Typbezeichner{\textgreater}Name
\end{itemize}
\begin{center}
\tablefirsthead{}
\tablehead{}
\tabletail{}
\tablelasttail{}
\begin{supertabular}{m{3.555cm}|m{1.3169999cm}}
Variablenscope &
Präfix\\\hline
Lokale \ Variable &
~
\\
Membervariable &
m\\
Statische Variable &
ms\\
Argument &
a\\
Rückgabewert &
r\\
\end{supertabular}
\end{center}
\begin{itemize}
\item Referenzsymbole direkt hinter den Typ: UINT8* value; UINT8\& value = a;
\item Methoden: mehrere Wörter, erstes Zeichen klein, jedes weitere Wort beginnt mit Großbuchstaben: getNextAndIncrement()
\item Klassen: ein oder mehrere Wörter, beginnen jeweils mit Großbuchstaben: \newline
JapCascadeMonitorView
\item Interfaces: IConnection
\item Abstrakte Klassen: AbstractConnection
\item Mix – Klassen beginnen mit CA: CAMsg 
\item Testklassen haben angehängtes Test: CAMsgTest
\item Dateiendungen: .java, .hpp, .cpp
\end{itemize}

\bigskip


\bigskip

Type Conventions

\begin{itemize}
\item Zu den einfachen Datentypen siehe Tabelle in Kapitel \ref{bkm:Typkonventionen}.
\item Java: Konstante Objekte nur über Interface definieren: Immutable{\textless}Classname{\textgreater};\newline
nicht-konstante Methoden im Interface auslassen;\newline
Instanzierung über final ImmutableMyClass A = new MyClass();
\item Variablen: nur private, public und protected sind verboten (außer in Strukturen)!
\item Methoden: so konstant wie möglich definieren
\item Klassen: möglichst kein statischer Code und keine Singletons
\item Java-Klassen: immer als final deklarieren
\item C++-Klassen: Templates sind verboten
\item Threads: Runnable implementieren, bzw. die Klasse CAThread verwenden
\item C++-Ausnahmen: jede Methode gibt Fehlercode nach folgendem Schema zurück:\newline
SINT32 doSomething(UINT32 a\_u32Value, Object\& r\_Object)
\end{itemize}

\bigskip

D

\begin{itemize}
\item Standard ist javadoc
\item Dokumentation wird vor der Implementierung geschrieben
\item Sprache ist Englisch (UK)
\item Todo-Tag benutzen, wenn volleFunktionalität nicht implementiert ist:\newline
/** @todo Begründung */
\end{itemize}

\bigskip

O

\begin{itemize}
\item maximale Zeilenlänge:110 Zeichen
\item Funktionsparameter über mehrere Zeilen mit zwei Tabs einrücken
\item Einrücktiefe: ein Tabulator (4 Leerzeichen)
\item geschweifte Klassern \{\}: in die nächste Zeile, beide Klammern auf gleicher Höhe
\item runde Klammern (): direkt hinter den Auslöser, bei Schlüsselwörtern ein Leerzeichen Abstand
\item Komma steht direkt hinter Methodenargumenten, danach ein Leerzeichen
\item siehe auch Kapitel \ref{bkm:Codierungskonvetionen} zu C!
\end{itemize}

\bigskip

Test

\begin{itemize}
\item Unittests sind vorgeschrieben
\item Testbibliotheken: JUnit bzw. CppUnit
\item Tests müssen vor der eigentlichen Implementierung geschrieben werden
\item zur genaueren Beschreibung siehe Kapitel \ref{bkm:Testen}
\end{itemize}
\end{document}
