File: README-for-developers

package info (click to toggle)
hepmc3 3.1.2-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 14,116 kB
  • sloc: fortran: 66,849; cpp: 13,604; ansic: 1,374; xml: 109; sh: 72; makefile: 33
file content (102 lines) | stat: -rw-r--r-- 3,234 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
-------------------------------------------------
PLEASE ADHERE TO THESE RULES WHEN ADDING NEW CODE
-------------------------------------------------

This will help keep the code uniform and will greatly improve readability
of the code for new developers or old ones going back into the code after
several years.

-------------
GENERAL RULES
-------------

1) We follow HepMC 2 naming conventions:
   - "snake_case" style of function and variable naming
   - "CamelCase" style of class naming
   - class/struct variables start from m_
   - enum values are ALL-CAPS
   - getters do not use 'get_' prefix
   - setters use 'set_' prefix

2) Remember to mark 'const' functions accordingly

3) HepMC follows no-throw policy, as in: no part of the code
   should throw an exception or use 'exit', etc. to end the program.
   All critical cases should be checked and when needed,
   an error should be printed.

4) Declare use of each std class separately.
   'using std::vector' instead of 'using namespace std'

5) Use pre-defined macros for any text output outside of print() functions.
   Precede any text with class and function name:

   ERROR(    "GenEvent::test: No particles in the event!" )
   WARNING(  "GenEvent::test: Only one particle present!" )
   DEBUG( 3, "GenEvent::test: Has end vertex: " << (bool)end_vertex() )

   DEBUG_CODE_BLOCK(
       int x = 10*10;
       DEBUG( 3, "GenEvent::test: This should be 100: " << x )
       event->print();
   )

6) Whenever you need an output for debugging, always use appropriately
   commented DEBUG( 10, "info" ) block. This would make things easier if you
   later decide it's worth to leave the debug info in the code.

7) DEBUG and DEBUG_CODE_BLOCK statements are not compile in release mode
   so use them at will. To avoid information flooding use appropriate
   debug levels for specific types of debug information:
   - level 1  - critical, short info
   - level 10 - less important, longer info

------------
CODING STYLE
------------

1) Do not use TABs to indent code.
2) Keep your code clean of trailing spaces
3) Keep in mind vertical code alignment. Especially in header files and
   in variable initialization. Makes these sections much easier to quickly
   glance over.

4) We use One True Brace Style, as in:

void function_name() {
    // ...
}


--------------
COMMENTS STYLE
--------------

1) When writing a comment that goes into documentation, use
   doxygen-style comments with keywords starting from '@', e.g.:

Comment block:

/**
 *  @file GenEvent.h
 *  @brief Definition of \b class GenEvent
 *
 *  @class HepMC3::GenEvent
 *  @brief Stores event-related information
 *
 *  Manages GenParticle and GenVertex objects
 *
 */

One-line comment:
int variable; //!< @todo This variable is probably useless

Parts that do not go into documentation (e.g. steps of an algorithm)
can be commented using usual // or /* */ comments.

2) Keep all of your code documented. Running: "cd doc/doxygen; make"
   should give no warnings about missing documentation

3) Use @bug @todo keywords to mark problems found in the code. They go
   on separate lists in the documentation so we can keep track of them
   at any time. Remove these keywords after fixing the issue.