template: STYLE.md annotate

annotate STYLE.md @ 32:651aee870e36

Add paragraph about std::string_view

author	David Demelier <markand@malikania.fr>
date	Wed, 18 Jul 2018 13:55:49 +0200
parents	5ea2876ac37a
children	793a60620477

rev	line source
17 314e8bb2659a Rename STYLE_CPP.md to STYLE.md David Demelier <markand@malikania.fr> parents: 16 diff changeset	1 PROJECT NAME CODING STYLE
314e8bb2659a Rename STYLE_CPP.md to STYLE.md David Demelier <markand@malikania.fr> parents: 16 diff changeset	2 =========================
314e8bb2659a Rename STYLE_CPP.md to STYLE.md David Demelier <markand@malikania.fr> parents: 16 diff changeset	3
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	4 General
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	5 =======
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	6
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	7 - Always use 4 spaces as indentation (expect Makefiles),
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	8 - Use UTF-8 charset,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	9 - Use Unix line endings,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	10 - Never write two blank consecutives blank lines,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	11
17 314e8bb2659a Rename STYLE_CPP.md to STYLE.md David Demelier <markand@malikania.fr> parents: 16 diff changeset	12 C++
314e8bb2659a Rename STYLE_CPP.md to STYLE.md David Demelier <markand@malikania.fr> parents: 16 diff changeset	13 ===
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	14
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	15 Style
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	16 -----
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	17
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	18 - Do not exceed 120 characters for lines of code,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	19 - Do not exceed 80 characters for comments,
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	20
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	21 ### Braces
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	22
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	23 Braces follow the K&R style, they are never placed on their own lines except for
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	24 function definitions.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	25
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	26 Do not put braces for single line statements.
10 eaae1fcabca8 Update braces style David Demelier <markand@malikania.fr> parents: 9 diff changeset	27
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	28 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	29 if (condition) {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	30 apply();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	31 add();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	32 } else
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	33 ok();
10 eaae1fcabca8 Update braces style David Demelier <markand@malikania.fr> parents: 9 diff changeset	34
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	35 if (condition)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	36 validate();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	37
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	38 if (foo)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	39 state = long + conditional + that + requires + several + lines +
10 eaae1fcabca8 Update braces style David Demelier <markand@malikania.fr> parents: 9 diff changeset	40 to + complete;
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	41 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	42
10 eaae1fcabca8 Update braces style David Demelier <markand@malikania.fr> parents: 9 diff changeset	43 Functions require braces on their own lines.
eaae1fcabca8 Update braces style David Demelier <markand@malikania.fr> parents: 9 diff changeset	44
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	45 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	46 void function()
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	47 {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	48 }
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	49 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	50
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	51 And a lambda has its braces on the same lines too:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	52
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	53 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	54 sort([&] (auto&) {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	55 return true;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	56 });
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	57 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	58
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	59 ### Spaces
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	60
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	61 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	62 its argument.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	63
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	64 Normal function calls do not require it.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	65
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	66 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	67 if (foo)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	68 destroy(sizeof (int));
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	69 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	70
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	71 ### References and pointers
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	72
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	73 References and pointers are always next to the type name and not the variable.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	74
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	75 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	76 T& get(const std::string& name);
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	77
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	78 int* p = &x;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	79 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	80
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	81 ### Naming
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	82
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	83 - English names,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	84 - Member variables have trailing underscore (e.g foo\_bar\_),
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	85 - No hungarian notation.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	86
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	87 Everything is in `underscore_case` except template parameters and macros.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	88
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	89 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	90 #if defined(FOO)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	91 # include <foo.hpp>
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	92 #endif
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	93
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	94 namespace baz {
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	95
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	96 class object {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	97 private:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	98 std::string name_;
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	99
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	100 public:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	101 inline const std::string& name() const noexcept
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	102 {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	103 return name_;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	104 }
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	105 };
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	106
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	107 template <typename Archive>
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	108 void open(const Archive& ar)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	109 {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	110 bool is_valid = false;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	111 }
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	112
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	113 } // !baz
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	114 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	115
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	116 ### Header guards
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	117
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	118 Do not use `#pragma once`.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	119
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	120 Header guards are usually named `PROJECT_COMPONENT_FILENAME_HPP`.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	121
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	122 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	123 #ifndef FOO_COMMON_UTIL_HPP
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	124 #define FOO_COMMON_UTIL_HPP
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	125
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	126 #endif // !FOO_COMMON_UTIL_HPP
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	127 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	128
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	129 ### Enums
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	130
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	131 Enumerations constants are always defined in separate line to allow commenting
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	132 them as doxygen.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	133
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	134 Enum class are encouraged.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	135
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	136 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	137 enum class color {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	138 blue,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	139 red,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	140 green
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	141 };
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	142 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	143
16 780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	144 ### Switch
780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	145
780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	146 In a switch case statement, you must not declare variables and not indent
780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	147 cases.
780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	148
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	149 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	150 switch (variable) {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	151 case foo:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	152 do_some_stuff();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	153 break;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	154 default:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	155 break;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	156 }
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	157 ```
16 780c138ab41d Add a note about switch David Demelier <markand@malikania.fr> parents: 14 diff changeset	158
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	159 ### Files
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	160
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	161 - Use `.cpp` and `.hpp` as file extensions,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	162 - Filenames are all lowercase.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	163
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	164 ### Comments
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	165
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	166 Avoid useless comments in source files. Comment complex things or why it is done
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	167 like this. However any public function in the .hpp must be documented as
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	168 doxygen without exception.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	169
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	170 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	171 /*
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	172 * Multi line comments look like
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	173 * this.
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	174 */
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	175
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	176 // Short comment
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	177 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	178
2 1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	179 Use `#if 0` to comment blocks of code.
1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	180
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	181 ```cpp
2 1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	182 #if 0
1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	183 broken_stuff();
1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	184 #endif
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	185 ```
2 1e34b51d9c52 Add note about if 0 David Demelier <markand@malikania.fr> parents: 1 diff changeset	186
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	187 ### Includes
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	188
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	189 The includes should always come in the following order.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	190
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	191 1. C++ headers
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	192 2. C header
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	193 3. Third party libraries
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	194 4. Application headers in ""
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	195
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	196 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	197 #include <cstring>
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	198 #include <cerrno>
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	199
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	200 #include <sys/stat.h>
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	201
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	202 #include <libircclient.h>
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	203
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	204 #include "foo.h"
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	205 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	206
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	207 Note: always use C++ headers for C equivalent, stdio.h -> cstdio, etc.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	208
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	209 Programming
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	210 -----------
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	211
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	212 ### C language
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	213
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	214 Do not use old C stuff like `void *`, `srand/rand`, `printf` or anything that
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	215 can be rewritten in modern C++.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	216
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	217 ### RTTI
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	218
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	219 Usage of `dynamic_cast` and `typeid` are completely disallowed in any shape of
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	220 form.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	221
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	222 ### Arguments
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	223
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	224 It is recommended to pass parameters by value or const reference. Usage of
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	225 non-const reference as output parameter is discouraged and should be avoided
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	226 in many case because it does not allow chaining of expressions like:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	227
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	228 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	229 std::cout << reverse(upper(clean(" hello world! "))) << std::endl;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	230 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	231
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	232 If your function is designed to return a modified value passed as argument, it
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	233 is better to take it by value and modify it directly.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	234
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	235 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	236 std::string clean(std::string input)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	237 {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	238 if (!input.empty() && input.back() == '\r')
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	239 input.pop_back();
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	240
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	241 return input;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	242 }
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	243 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	244
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	245 Never pass primitive types as const value.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	246
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	247 ### Assertions
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	248
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	249 Use the `assert` macro from the cassert header file to verify programming
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	250 errors.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	251
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	252 For example, you may use `assert` to verify that the developer access the data
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	253 between the bounds of an array:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	254
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	255 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	256 T& operator[](unsigned index)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	257 {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	258 assert(index < length_);
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	259
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	260 return data_[index];
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	261 }
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	262 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	263
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	264 The `assert` macro is not meant to check that a function succeeded, this code
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	265 must not be written that way:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	266
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	267 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	268 assert(listen(10));
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	269 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	270
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	271 ### Exceptions
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	272
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	273 You must use exceptions to indicate an error that was unexpected such as:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	274
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	275 - Failing to open a file,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	276 - I/O unexpected errors,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	277 - Parsing errors,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	278 - User errors.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	279
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	280 You may use the C++ standard exceptions defined in the stdexcept header but if
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	281 you need to carry more data within your exception, you should derive from
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	282 `std::exception`.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	283
14 55bb3689093f Add chapter about error codes David Demelier <markand@malikania.fr> parents: 13 diff changeset	284 ### Error code
55bb3689093f Add chapter about error codes David Demelier <markand@malikania.fr> parents: 13 diff changeset	285
55bb3689093f Add chapter about error codes David Demelier <markand@malikania.fr> parents: 13 diff changeset	286 You should not use error codes to indicate errors, instead use exceptions.
55bb3689093f Add chapter about error codes David Demelier <markand@malikania.fr> parents: 13 diff changeset	287 Error codes are allowed in Boost.Asio though.
55bb3689093f Add chapter about error codes David Demelier <markand@malikania.fr> parents: 13 diff changeset	288
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	289 ### Free functions
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	290
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	291 Basic utility functions should be defined in a namespace as a free function not
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	292 as a static member function, we're doing C++ not Java.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	293
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	294 Example:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	295
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	296 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	297 namespace util {
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	298
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	299 std::string clean(std::string input);
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	300
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	301 } // !util
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	302 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	303
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	304 ### Variables initialization
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	305
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	306 Use parentheses to initialize non primitive types:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	307
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	308 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	309 throw std::runtime_error("foo");
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	310
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	311 my_class obj("bar");
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	312 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	313
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	314 Use brace initialization when you want to use an initializer list, type
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	315 elision:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	316
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	317 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	318 std::vector<int> v{1, 2, 3};
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	319
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	320 foo({1, 2}); // type deduced
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	321
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	322 return { "true", false }; // std::pair returned
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	323 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	324
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	325 Use the assignment for primitive types:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	326
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	327 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	328 int x = 123;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	329 bool is_valid = true;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	330 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	331
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	332 ### Classes
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	333
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	334 Classes are usually defined in the following order:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	335
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	336 1. Public inner types (enums, classes),
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	337 2. Protected/private members and functions
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	338 3. Public static functions.
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	339 3. Public member functions
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	340 4. Public virtual functions.
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	341
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	342 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	343 class foo {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	344 public:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	345 enum class type {
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	346 a,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	347 b
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	348 };
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	349
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	350 private:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	351 int member_{0};
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	352
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	353 public:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	354 void some_function();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	355 };
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	356 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	357
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	358 ### Structs
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	359
31 5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	360 Use structs for objects that only need to store public data and have no
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	361 invariants. For example PODs and traits match this criteria:
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	362
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	363 ```cpp
31 5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	364 struct point {
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	365 int x{0};
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	366 int y{0};
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	367 };
31 5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	368
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	369 template <>
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	370 struct info_traits<point> {
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	371 template <typename Archive>
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	372 static void serialize(Archive& ar, const point& point)
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	373 {
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	374 ar.write(point.x);
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	375 ar.write(point.y);
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	376 }
5ea2876ac37a Relax usage of structs David Demelier <markand@malikania.fr> parents: 28 diff changeset	377 };
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	378 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	379
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	380 ### Return
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	381
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	382 The preferred style is to return early in case of errors. That makes the code
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	383 more linear and not highly indented.
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	384
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	385 This code is preferred:
a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	386
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	387 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	388 if (a_condition_is_not_valid)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	389 return nullptr;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	390 if (an_other_condition)
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	391 return nullptr;
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	392
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	393 auto x = std::make_shared<object>();
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	394
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	395 x->start();
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	396 x->save();
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	397
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	398 return x;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	399 ```
0 a8462a503697 Initial import David Demelier <markand@malikania.fr> parents: diff changeset	400
1 9bf9b4634339 Update return statement David Demelier <markand@malikania.fr> parents: 0 diff changeset	401 Additional rules:
9bf9b4634339 Update return statement David Demelier <markand@malikania.fr> parents: 0 diff changeset	402
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	403 - Do never put parentheses between the returned value,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	404 - Do not put a else branch after a return.
13 4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	405
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	406 ### Auto
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	407
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	408 We encorage usage of `auto`, it reduces code maintainance as you don't need to
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	409 change your code when your rename types.
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	410
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	411 ```cpp
13 4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	412 auto it = std::find_if(v.begin(), v.end(), [&] (const auto& obj) {
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	413 return obj.key() == "foo";
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	414 });
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	415
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	416 for (const auto& pair : a_map)
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	417 std::cout << pair.first << " = " << pair.second << std::endl;
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	418 ```
13 4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	419
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	420 But do not use `auto` to write code like in python, this is not acceptable:
4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	421
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	422 ```cpp
13 4d6bf8b3446d Add chapter about auto David Demelier <markand@malikania.fr> parents: 12 diff changeset	423 auto o = my_object("foo");
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	424 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	425
32 651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	426 ### String views
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	427
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	428 Use `std::string_view` each time you need a string that you will not own, this
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	429 includes: temporary arguments, return values, compile time constants.
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	430
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	431 ```cpp
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	432 const std::string_view version("1.0");
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	433
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	434 auto find(std::string_view id) -> std::optional<int>
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	435 {
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	436 if (auto it = foo.find(id); it != foo.end())
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	437 return it->second;
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	438
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	439 return std::nullopt;
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	440 }
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	441 ```
651aee870e36 Add paragraph about std::string_view David Demelier <markand@malikania.fr> parents: 31 diff changeset	442
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	443 CMake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	444 =====
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	445
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	446 Style
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	447 -----
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	448
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	449 - Try to keep line shorter than 80 columns
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	450
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	451 ### Spaces
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	452
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	453 Each programming keyword (e.g. `if`, `foreach`, `while`) requires a single space
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	454 before its argument, otherwise write opening parenthese directly after.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	455
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	456 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	457 foreach (c ${COMPONENTS})
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	458 string(TOUPPER ${c} CMP)
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	459
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	460 if (${WITH_${CMP}})
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	461 add_executable(${c} ${c}.cpp)
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	462 endif ()
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	463 endforeach ()
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	464 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	465
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	466 ### Line breaks
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	467
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	468 When CMake lines goes too long, you should indent arguments at the same level,
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	469 it's also common to see named argument values indented even more.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	470
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	471 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	472 set(
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	473 FILES
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	474 ${myapp_SOURCE_DIR}/main.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	475 ${myapp_SOURCE_DIR}/foo.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	476 ${myapp_SOURCE_DIR}/bar.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	477 )
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	478
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	479 command_with_lot_of_arguments(
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	480 TARGET foo
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	481 INSTALL On
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	482 SOURCES
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	483 ${myapp_SOURCE_DIR}/main.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	484 ${myapp_SOURCE_DIR}/foo.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	485 ${myapp_SOURCE_DIR}/bar.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	486 COMMENT "Some comment"
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	487 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	488
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	489 Modern CMake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	490 ------------
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	491
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	492 CMake evolves over time, if you have read very old articles there is a chance
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	493 that what you have read is actually deprecated and replaced by other features.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	494 The following list is a short summary of modern CMake features that you must
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	495 use.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	496
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	497 ### Imported targets
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	498
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	499 When they are available, use imported targets rather than plain variables. They
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	500 offer complete dependency tracking with options and include directories as well.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	501
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	502 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	503 find_package(Boost COMPONENTS system)
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	504 target_link_libraries(main Boost::system)
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	505 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	506
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	507 ### Use generator expressions
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	508
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	509 Use generator expressions as much as you can, they offer much more flexibility
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	510 in case of multiple generators. Remember that CMake is not meant to be used only
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	511 with Makefiles.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	512
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	513 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	514 target_link_libraries(
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	515 myapp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	516 $<$<STREQUAL:${CMAKE_SYSTEM_NAME},Windows>:shlwapi>
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	517 $<$<STREQUAL:${CMAKE_SYSTEM_NAME},Linux>:dl>
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	518 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	519
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	520 Warning: do never test against `CMAKE_BUILD_TYPE` in any CMakeLists.txt, IDEs
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	521 like Visual Studio will mismatch what you'll put in the conditions.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	522
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	523 ### Avoid global scoping
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	524
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	525 The following commands must be avoided as much as possible:
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	526
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	527 - `link_directories`,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	528 - `link_libraries`,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	529 - `include_directories`,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	530 - `add_definitions`.
25 9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	531
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	532 They pollute the global namespace, all targets defined after these commands will
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	533 be built against those settings. Instead, you should use the per-targets
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	534 commands.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	535
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	536 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	537 target_include_directories(
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	538 mylib
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	539 PUBLIC
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	540 $<BUILD_INTERFACE:${mylib_SOURCE_DIR}>
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	541 $<INSTALL_INTERFACE:include>
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	542 )
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	543 target_link_libraries(mylib foo)
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	544 ```
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	545
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	546 ### Defining sources
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	547
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	548 You MUST never use any kind of `file(GLOB)` commands to list sources for an
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	549 executable. CMake is designed to be re-called by itself only when required,
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	550 having such a construct will not let CMake be able to detect if you have
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	551 added/removed files in your source directory. Instead, you MUST always specify
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	552 all source by hands.
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	553
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	554 ```cmake
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	555 set(
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	556 FILES
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	557 ${myapp_SOURCE_DIR}/main.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	558 ${myapp_SOURCE_DIR}/a.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	559 ${myapp_SOURCE_DIR}/b.cpp
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	560 )
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	561
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	562 add_executable(myapp ${FILES})
9573e6c9ac97 Add CMake guide in STYLE.md David Demelier <markand@malikania.fr> parents: 17 diff changeset	563 ```
27 0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	564
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	565 Markdown
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	566 ========
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	567
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	568 Lists
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	569 -----
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	570
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	571 Use hyphens for unordered lists for consistency, do not indent top level lists,
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	572 then indent by two spaces each level
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	573
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	574 ```markdown
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	575 - unordered list 1
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	576 - unordered list 2
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	577 - sub unordered item
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	578
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	579 1. unordered list 1
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	580 2. unordered list 2
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	581 2.1. sub unordered item
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	582 ```
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	583
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	584 Code blocks
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	585 -----------
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	586
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	587 You can use three backticks and the language specifier or just indent a block by
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	588 for leading spaces if you don't need syntax.
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	589
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	590 ```cpp
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	591 std::cout << "hello world" << std::endl;
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	592 ```
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	593
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	594 And without syntax:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	595
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	596 ```markdown
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	597 This is simple code block.
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	598 ```
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	599
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	600 Tables
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	601 ------
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	602
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	603 Tables are supported and formatted as following:
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	604
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	605 ```markdown
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	606 \| header 1 \| header 2 \|
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	607 \|----------\|----------\|
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	608 \| item 1 \| item 2 \|
0706d01e073f Update markdown convention and add it to STYLE.md David Demelier <markand@malikania.fr> parents: 25 diff changeset	609 ```
28 1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	610
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	611 Alerts
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	612 ------
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	613
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	614 It's possible to prefix a paragraph by one of the following topic, it renders a
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	615 different block depending on the output format:
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	616
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	617 - Note:
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	618 - Warning:
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	619 - Danger:
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	620
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	621 Then, if the paragraph is too long, indent the text correctly.
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	622
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	623 ```markdown
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	624 Note: this is an information block that is too long to fit between the limits so
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	625 it is split and indented.
1a9a76f94955 Add alerts in markdown style David Demelier <markand@malikania.fr> parents: 27 diff changeset	626 ```

Mercurial > template

annotate STYLE.md @ 32:651aee870e36