Cheetah - SKA - PSS - Prototype Time Domain Search Pipeline
doc/developers_guide.md
1 \anchor dev\_guide
2 # Developers Guide
3 
4 ## Dependencies
5 Do not introduce any new dependencies on any other product without consultation
6 
7 ## Build Products
8 The project will build the pipeline executable, two c++ libraries, and their associated header files.
9 One library will support the main product and the second a library is a set of utilitites to aid in unit testing code
10 that uses the main library.
11 
12 # Repository
13 ## Workflow and Branches
14  - Use the gitlab workflow (https://repo.oerc.ox.ac.uk/help/workflow) as much as possible.
15  - Never work directly on the master branch - this is the "stable release" and is tightly controlled
16  - The master shall compile and pass all unit tests at all times.
17  - Commits to the master must only be done after code review and from a working dev branch
18  - devs should keep their own branch in sync with the dev branch.
19  - The dev shuold compile and pass all unit tests. Any build breaks should receive top priority.
20  - Only merge from a feature branch that is already synced with the dev branch.
21  - Commits to the dev should usually only be done after code review and from a working feature branch
22  - use the gitlab merge request feature for feature->dev branch merges
23 
24 ## Repository Structure
25 cmake : project specific files for configuring the build system
26 tools : useful things to aid the developer such as a class template generator
27 doc : documentation & doc templates, with the exception of the API doc of the classess. Also see module doc directoy.
28 cheetah : this is the src code for the cheetah library. It is organised as a set of modules with
29  the following minimal structure (following the boost conventions for templates)
30 
31  cheetah +
32  + <module\_name> + In this directory only put header files that you wish exposed to module users
33  + doc Add additional doxygen documentation for tutorials etc here.
34  + examples src code example uses
35  + src All .cpp files for the library and internal headers
36  + detail All .cpp implementations details for template classes that cannot be precompiled
37  + test\_utils + Include files for the supporting test library
38  + src Implementation details (.cpp files) for the test library
39  + detail Template implementation details for the test support library
40  + test The unit test directory. Header files for unit tests live here
41  + src Implementation details (.cpp files) for unit tests
42 
43 
44 cheetah/test : the location of tests and any public headers for the cheetah integration tests
45 cheetah/test/src : the location of all test implementation coded
46 
47 # The Build System
48 This project uses cmake as is build system. See the notes in the CMakeLists.txt file in the top directory
49 
50 ## Adding a src file/class
51  - Each time you add a new class, in order for it to build you will need to add a reference to it in the appropriate CMakeLists.txt file
52  (either in cheetah/module\_name/CMakeLists.txt or cheetah/module\_name/test\_utils/CMakeLists.txt)
53  - place source names in alphabetical order when adding to variables
54  - You can use the class tool (in the tools directory) to autogenerate a suitable class template
55 
56 ## Adding a submodule
57  - To add a submodule use the SUBPACKAGE macro (see doc in cmake/subpackage.cmake).
58  To simplify, the purpose of this macro is to add the submodules contribution to the lib\_src\_${arch} variables which
59  are used to define the contents of the cheetah libraries.
60  (n.b ensure the variables defined in the submodule use PARENT\_SCOPE qualifier)
61 
62 ## Including a dependency in the build system
63  - unless essential (and approved to be so) make the dependency optional, and off by default. Allow the "ENABLE\_<feature>" flag to enable.
64  - add a new file cmake file in the cmake directory for that product/feature and include this from cmake/dependencies.cmake
65  - Stick to a standard convention for naming the product location.
66  TODO - decide what these should be
67  i.e. <NAME>\_ROOT, <NAME>\_INCLUDE\_DIRECTORIES, <NAME>\_LIBRARIES, FOUND\_<NAME>
68  - Test these can be overriden succesfully from the command line and non-system versions can be specified easily
69 
70 
71 # Coding Conventions
72 Coding conventions are used in this project to ensure conformity in style and to help
73 reduce any of the very many pitfalls c++ programming can introduce,
74 Remember that these are just general guidelines. Try and stick to them as much as possible,
75 but there will always be cases where doing it differently is justified. Document these exceptions with comments in the code.
76 
77 ## Namespaces
78 - all classes shall be in the ska::cheetah::<module\_name> or ska::cheetah::<module\_name>::test namespace as appropriate.
79 - avoid using where possible "using namespace ..". Avoid completely in public header files.
80 
81 ## Naming Conventions
82 - class names shall start with a capital letter and be CamelCased
83 - method and functions shall be all lower case, with word seperation with an "\_" e.g. do\_something()
84 - variable and member names shall be all lower case
85 - all members shall be prefixed with an underscore "\_"
86 - getters and setters should be overloads with the same function name e.g.
87 ```
88  // getter
89  ThingyType thingy() const;
90 
91  // setter
92  void thingy(ThingyType const& thingy);
93 ```
94 
95 
96 ## Indendation & CRLF of source files
97 - use 4 spaces instead of tab.
98 - use LF in preference to CRLF
99 - namespaces shall not be indented
100 - there shall be no redundant whitespace at the end of any line
101 - add a space or new line after each comma ',' in a list
102 
103 ## C++ Files
104 Each class shall have its own separate cpp and header file. The name of the file should be the same as the class with the .h or .cpp extension
105 Do not mix two classes together in the same file.
106 An exception to this rule can be made where there is a private Internal Implementation class unique to the
107 class being implemented AND it is not confusing to do so.
108 
109 - All classes must be in the ska, cheetah namespace
110 - Header files must start with.
111 ```
112 #ifdef SKA\_CHEETAH\_<MODULE\_NAME>\_<CLASS\_NAME>\_H
113 #define SKA\_CHEETAH\_<MODULE\_NAME>\_<CLASS\_NAME>\_H
114 ... body of header
115 #endif // SKA\_CHEETAH\_<MODULE\_NAME>\_<CLASS\_NAME>\_H
116 ```
117  In the tool directory you will find a class template generator that you may find helpful.
118 ## Documentation
119 - Add doxygen style comments for each method and each parameter in every public header file.
120 - Think about adding an example of the use of each method
121 - Document the bounds of any parameter
122 - Document untested use cases/parameters (i.e. where you have not provided an explicit unit test)
123 - Add comments as appropriate in the cpp file and non-public headers.
124 
125 ## Constructors
126 - Never use new inside a constructor parameter list e.g.
127 ```
128 dodgy = MyClass(new BadThingToDo());.
129 ```
130  This could easily lead to a memory leak if the constructor of MyClass should fail.
131 - Do not create long lists of parameters with the same types. Use strong typeing as much as possible to
132  get your compiler to do the debugging for you.
133  e.g. thing(int x\_dimension, int y\_dimension, int subject\_index)
134  could become:
135  thing( Dimension x, Dimension y, SubjectIndex i );
136  or even:
137  thing( DimensionX x, DimensionY y, SubjectIndex i );
138 - align commas in the initialiser list on seperate lines
139  e.g.
140 ```c++
141  MyClass(A a, B b)
142  : \_a(a) // indent : by 4 spaces on its own line
143  , \_b(b) // align comma under the :
144  {
145  }
146 ```
147 
148 ## Inheritance
149 - Any base class destructors should be marked virtual if they are public (or protected if they are not) if they are intended to be used for polymorphism
150 - Any deriving class shall provide a (public/protected/private as appropraite) typedef BaseT that is the base class type
151 
152 ## Class Declarations
153 - all members shall be prefixed with an underscore "\_"
154 - all members shall be made either private or protected as appropriate
155 - indent private, protected, amd public keywords by 4 spaces
156 - always use the override keyword when you inherit from a method
157 - do not mix members, typdefs, or functions together, but keep them in their own public:, protected:, or private: blocks.
158 - all public methods and typedef should be documented
159 - header shall be ordered as much as possible as follows, each type in their own public/private/protected block:
160  e.g.
161 ```c++
162  class MyClass
163  {
164  public:
165  // typdefs
166 
167  public:
168  // public methods before protected
169 
170  protected:
171  // protected methods before private
172 
173  private:
174  // private methods
175 
176  protected:
177  // protected members
178 
179  private:
180  // private members
181  };
182 ```
183 
184 ## Exceptions
185 - Prefer exceptions, but use return codes where it is more appropriate
186 - No exceptions to be propagated outside of its thread - think about passing it along with a std::exception\_ptr.
187 - Use std::exceptions as appropriate, or panda::Error if you want to add messages with runtime information.
188 - If you need your own exceptions for some reason, try and avoid any memory allocation of the exception. i.e follow the std::exception model
189  It should also be OK to inherit from panda::Error.
190 
191 ## Unit Tests
192 - gtest shall be used as the unit test framework
193 - each class should have its own unit test suite which shall be in files <CLASS\_NAME>Test.cpp and <CLASS\_NAME>Test.h in the unit test directory
194 - any common functionality should be considered for inclusion in the test utility library, and provded with appropriate headers and documentation
195 - all unit tests should be verified to pass before making a merge reuest
196 - unit test names shall follow the function naming convention of the c++ irrespective of whether it is implemented as a class or not
197 - unit test groups shall be CamelCased
198  e.g
199 ```
200 TEST\_F(MyTestGroup, test\_something\_really\_well)
201 ```
202 - to run all the tests
203 ```
204 make test
205 ```
206 - to run all the tests and generate a test coverage report (only in 'coverage' type builds)
207 ```
208 make coverage\_report\_test
209 ```
210 
211 ## Using CUDA
212 If CUDA is available and it has been explicitly activated in the build system, the ENABLE\_CUDA flag will be set.
213 Use this flag to ensure your code compiles and your unit tests run with or without CUDA availability.
214 
215 Setting specific compile flags for subpackage products shall be done through the cuda\_subpackage\_compile macro:
216 e.g.
217 
218 cuda\_subpackage\_compile(${lib\_src\_cuda} OPTIONS "-arch compute\_35")
219 
220 ## Extending std classes
221 While this style guide requests CamelCase typedefs, there are cases where the standard convention is to use lower\_case
222 names for typedefs. This is true in the case of classes that extend or can be used in place of classes from the
223 standard library (or as in the case of thrust, boost, etc. libraries that follow conventions from the standard library) that conform to specific concepts. Places where this is done should be clearly documented.