diff --git a/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/StyleGuideAndNotes.dox b/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/StyleGuideAndNotes.dox index 2ea36ad6b4..f06de7fe39 100644 --- a/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/StyleGuideAndNotes.dox +++ b/Documentation/Doxygen/3-DeveloperManual/Starting/GettingToKnow/StyleGuideAndNotes.dox @@ -1,469 +1,469 @@ /** \page StyleGuideAndNotesPage The MITK Style Guide and Technical Notes \tableofcontents The following document is a description of the accepted coding style for the Medical Imaging Interaction Toolkit (MITK). Developers who wish to contribute code to MITK should read and adhere to the standards described here. \section StyleGuideAndNotesPage_NameConventions Naming Conventions \li Using case change to indicate separate words @code ImageFilter PixelType DataStorage NodePredicateProperty @endcode \li Underscores are not used e.g. Image_Filer, _Node \li Variable names should convey the meaning behind the code @code BoundingBox::Pointer boundingBox = BoundingBox::New(); @endcode \li Names are generally spelled out @code mitk::DataNode* node; @endcode \li Abbreviation are allowable when in common use e.g. ROI for Region of Interest \subsection StyleGuideAndNotesPage_NamingClasses Naming Classes \li Classes are named beginning with a capital letter \li Classes are named according to the following general rule: @code class name = @endcode \li Examples of concepts \n Accessor: Access and convert between types e.g. NullScalarAccessor \n Container: A container of objects such as points or images e.g. VectorContainer \n Filter: A class that participates in the data processing pipeline e.g. AddImageFilter \n Mapper: Transform data from one form into another e.g. ContourMapper2D \n Reader/Writer: A class that reads/writes a single data object e.g. VtkSurfaceReader \n \subsection StyleGuideAndNotesPage_NamingFiles Naming Files \li MITK classes like @a ExampleClass should be in namespace @a mitk and their corresponding files should be named @a mitkExampleClass.h/.cpp. @code mitk::DataStorage @endcode \li Qt specific MITK classes like @a QmitkListView should have the prefix Qmitk in their class names and their corresponding files should be named @a QmitkListView.h/.cpp. @code QmitkDataStorageComboBox @endcode \li Header Files ends with an .h and \li Implementation Files with an .cpp or .txx for a template class \subsection StyleGuideAndNotesPage_NamingMethodsandFunctions Naming Methods and Functions \li Functions and methods are named beginning with a capital letter \li Referring to class methods in code, an explicit this-> pointer should be used @code mitk::DataStorage::SetOfObjects::ConstPointer all = this->GetAll(); @endcode \subsection StyleGuideAndNotesPage_NamingSignalSlots Naming Signal/Slots Methods and Functions \li Slots are named according to the following general rule @code On[variable name who send the signal][signal](); @endcode \li Example @code connect( loadImagePushButton, SIGNAL( clicked(bool ) ), SLOT( OnLoadImagePushButtonClicked( bool ) ) ); void mitk::Image::OnLoadImagePushButtonClicked( bool ) { ... Do something ... } @endcode \li Signals are named according to the following general rule @code Signal[MethodName](); @endcode \li Example @code emit SignalFinishedSegmentation(); @endcode \subsection StyleGuideAndNotesPage_NamingClassDataMembers Naming Class Data Members \li Class data members are prefixed with m_ @code m_Volumes m_OffsetTable m_ImageMask @endcode \li An exception to this rule, Qt class Data members are not prefixed and begin with a lower-case letter @code loadImageButton closeImageAction @endcode \subsection StyleGuideAndNotesPage_NamingLocalVariables Naming Local Variables \li Local variables first letter is lower-case @code offset data slicesIt @endcode \subsection StyleGuideAndNotesPage_NamingQtVariables Naming Qt Variables \li GUI variables ends with name of used QT tool. @code QPushButton* loadImagePushButton; QAction* closeImageAction; QCheckBox* hideImageCheckBox; QRadioButton* binaryImageRadioButton; @endcode \subsection StyleGuideAndNotesPage_NamingTypedefs Naming Typedefs \li Typedefs must end in the word Type @code typedef TPixel PixelType; typedef itk::Image< TPixel, VImageDimension > ImageType; typedef std::list ImageListType; @endcode \section StyleGuideAndNotesPage_Pointer Pointer \subsection StyleGuideAndNotesPage_DeclarationofPointers Declaration of Pointers \li Position of * pointers are connected with the variable @code int *counter; @endcode \li Analog to references @code int &counter; @endcode \subsection StyleGuideAndNotesPage_SmartPointer SmartPointer \li SmartPointers must be used for classes that have itk::Object as a base class. \li Assignment of a just created instance to a normal pointer results in a crash, since the reference count is decreased immediately to zero and the object is destroyed. @code itk::Object::Pointer object = itk::Object::New(); @endcode \li Static declarations are also forbidden and result into an exception when the scope of the variable is left, because the destructor is called while the reference count is still greater than zero. \li Note that using smart pointers requires using real (normal) pointers when setting input. If you want to return a newly created smart pointer that is not also kept within the class (e.g., if you write a Clone method), you have to return a smart pointer on output (compare itkMacro.h). If the smart pointer is kept within the class, returning a real (normal) pointer is sufficient. \li Testing a SmartPointer against NULL is done with the IsNull() and Is- NotNull() methods. A simple ==NULL issues a warning. \section StyleGuideAndNotesPage_Namespace Namespace \li MITK classes should be in namespace @a mitk @code mitk::Image::Pointer mitk::ImageGenerator::MakeImage() { // already in namespace mitk here! Image::Pointer image = mitk::Image::New(); ImageDecorator::Pointer decorator = mitk::ImageDecorator::New(); d->Decorate( image ); return image; } @endcode \li Constants in MITK for mitk::Operation and mitk::Action are set in namespace, so don't forget to add prefix mitk:: @code switch (actionId) { case mitk::AcMOVESELECTED: ....Do something ... break; default: break; } @endcode \section StyleGuideAndNotesPage_CodeLayoutandIndentation Code Layout and Indentation \subsection StyleGuideAndNotesPage_GeneralLayout General Layout \li Each line of code should take no more than 120 characters. \li Use lots of whitespace to separate logical blocks of code, intermixed with comments -\li DO NOT USE TABS. The standard indention is 2 spaces (see ITK Style Guide). Configure your +\li DO NOT USE TABS. The standard indention is 2 spaces (see ITK Style Guide). Configure your editor accordingly. \li DO NOT USE trailing whitespaces \li Declaration of variables should be one declaration per line @code int sliceNumber; char* stringName; ImageType::Pointer image; @endcode \subsection StyleGuideAndNotesPage_ClassLayout Class Layout \li Copyright @code /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ @endcode \li Includes [A .. Z] @code #include "... .h" @endcode \li Namespace @code namespace mitk { @endcode DO NOT litter your header with "using namespace;"! \li Class (Template) @code template class ClassName : public ImageBase { @endcode \li Typedefs @code public: ....typedefs.... @endcode \li Methods @code public: ....methods.... protected: ....methods.... private: ....methods.... @endcode \li QT Signals @code signals: Signal...(); @endcode \li QT Slots @code public slots: On...(); protected slots: On...(); @endcode \li Data Member @code private/protected: ....class data members.... }; } #endif @endcode \section StyleGuideAndNotesPage_UseofBraces Use of Braces \li Used to delimit the scope of an if, for, while, switch. \li Braces are placed on a line by themselves: @code for ( unsigned int i = 0; i < 3; ++i ) { ... do something ... } @endcode or @code if ( condition ) { ... do something ... } else if ( other condition ) { ... do something ... } else { ... do something ... } @endcode \li You can choose to use braces on a line with a code block when the block consists of a single line: @code if ( condition ) { foo = 1; } else if ( condition2 ) { foo = 3; } else { return; } @endcode or @code for ( unsigned int i = 0; i < 3; ++i) { x[i] = 0.0; } @endcode \section StyleGuideAndNotesPage_IncludeGuards Include Guards \li #inlcude guard is a particular construct used to avoid the problem of double inclusion when dealing with the #include directive. \li Naming convention for #inlcude guards is: ClassName_h \li Following example demonstrates a problem that can arise if #include guards are missing: Here, the file child.cpp has indirectly included two copies of the text in the header file grandfather.h. This causes a compilation error, since the structure type foo is apparently defined twice. @code grandfather.h struct foo { int m Member; }; father.h #include "grandfather.h" child.h #include "grandfather.h" #include "father.h" @endcode \subsection StyleGuideAndNotesPage_Useofincludeguards Use of #include guards \li Here, the first inclusion of grandfather.h causes the macro grandfather h to be defined. Then, when child.cpp includes grandfather.h the second time, the #ifndef test fails, and the preprocessor skips down to the #endif, thus avoiding the second definition of struct foo. The program compiles correctly. @code grandfather.h #ifndef grandfather h #define grandfather h struct foo { int m Member; }; father.h #include "grandfather.h" child.h #include "grandfather.h" #include "father.h" @endcode \section StyleGuideAndNotesPage_TechnicalNotes Some Technical Notes \li Use forward declarations in header files wherever possible. Only include those header files in a header file that are really necessary. Include the rest in the implementation file. \li For classes inheriting directly or indirectly from @a itk::LightObject (most of the MITK-classes do so), the class definition should include the mitkClassMacro. Additionally, if the class can be instantiated (normally the case, if the class is not abstract) and has @em only a constructor without parameters, the constructor should be declared protected and the @a itkFactorylessNewMacro should be used to create a @a New() method for instantiation. Here is an example: @code class ExampleClass : public SuperClassOfTheExampleClass { public: mitkClassMacro(ExampleClass, SuperClassOfTheExampleClass) itkFactorylessNewMacro(Self) [...] protected: ExampleClass(); virtual ~ExampleClass(); } @endcode \li Set- and Get-methods can be created with the macros @a itkSetObjectMacro(name,type) and @a itkGetObjectMacro(name,type), respectively, if the @a type is derived from @a itk::LightObject or @a itk::Object. There are also macros for other types, e.g., strings, see itkMacro.h. \li When using inner classes of a parent class which is templated, you have to use the keyword @a typename for gcc 3.x and standard compliance. For example, @a TreeChangeListener is an inner class of @a Tree, therefore use: @code class LinkedTree : public Tree { public: typedef typename LinkedTree::TreeChangeListener TreeChangeListener; [...] } @endcode Another example: @code typename std::vector::iterator pos = treeChangeListenerList.begin(); @endcode @a iterator is an inner class of @a vector. \li Constants in MITK for mitk::Operation and mitk::Action are set in namespace, so don't forget to add prefix @a mitk:: @code switch (actionId) { case mitk::AcMOVESELECTED: @endcode Prefixes for the constants are to be used like corresponding others. See file @a Interactions\\mitkBaseInteraction\\mitkInteractionConst.h for further details. \section StyleGuideAndNotesPage_AutomaticCodeFormatting Automatic Code Formatting We offer a .clang-format file, which can be used to automatically format code acceptably. \include .clang-format For an explanation of the different options check out http://clang.llvm.org/docs/ClangFormatStyleOptions.html */