Warning, /kdevelop/kdev-verapp/rules/Rules.md is written in an unsupported language. File is not indexed.
0001 Rules 0002 ===== 0003 0004 F001 Source files should not use the '\\r' (CR) character 0005 --------------------------------------------------------- 0006 0007 As a commonly accepted practice, line breaks are denoted by a single 0008 '\\n' (LF) character or by two characters "\\r\\n" (CRLF). A single 0009 appearance of '\\r' (CR) is discouraged. 0010 0011 **Compliance:** Boost 0012 0013 0014 F002 File names should be well-formed 0015 ------------------------------------- 0016 0017 The source file names should be well-formed in the sense of their 0018 allowed maximum length and directory depth. Directory and file names 0019 should start with alphabetic character or underscore. In addition, 0020 directory names should not contain dots and file names can have only one 0021 dot. 0022 0023 **Recognized parameters:** 0024 0025 Name Default Description 0026 ----------------------- --------- ------------------------------------------------- 0027 max-directory-depth 8 Maximum depth of the directory structure. 0028 max-dirname-length 31 Maximum length of the directory path component. 0029 max-filename-length 31 Maximum length of the leaf file name. 0030 max-path-length 100 Maximum length of the full path. 0031 0032 **Compliance:** Boost 0033 0034 0035 L001 No trailing whitespace 0036 --------------------------- 0037 0038 *Trailing whitespace* is any whitespace character (space or tab) that is 0039 placed at the end of the source line, after other characters or alone. 0040 0041 The presence of *trailing whitespace* artificially influences some 0042 source code metrics and is therefore discouraged. 0043 0044 As a special case, the trailing whitespace in the otherwise empty lines 0045 is allowed provided that the amount of whitespace is identical to the 0046 indent in the previous line - this exception is more friendly with less 0047 smart editors, but can be switched off by setting non-zero value for the 0048 `strict-trailing-space` parameter. 0049 0050 **Recognized parameters:** 0051 0052 Name Default Description 0053 ------------------------- --------- -------------------------------------- 0054 strict-trailing-space 0 Strict mode for trailing whitespace. 0055 0056 **Compliance:** Inspirel 0057 0058 0059 L002 Don't use tab characters 0060 ----------------------------- 0061 0062 *Horizontal tabs* are not consistently handled by editors and tools. 0063 Avoiding them ensures that the intended formatting of the code is 0064 preserved. 0065 0066 **Compliance:** HICPP, JSF 0067 0068 0069 L003 No leading and no trailing empty lines 0070 ------------------------------------------- 0071 0072 *Leading and trailing empty lines* confuse users of various tools (like 0073 `head` and `tail`) and artificially 0074 influence some source code metrics. 0075 0076 **Compliance:** Inspirel 0077 0078 0079 L004 Line cannot be too long 0080 ---------------------------- 0081 0082 The source code line should not exceed some *reasonable* length. 0083 0084 **Recognized parameters:** 0085 0086 Name Default Description 0087 ------------------- --------- ------------------------------------- 0088 max-line-length 100 Maximum length of source code line. 0089 0090 **Compliance:** Inspirel 0091 0092 0093 L005 There should not be too many consecutive empty lines 0094 --------------------------------------------------------- 0095 0096 The empty lines (if any) help to introduce more "light" in the source 0097 code, but they should not be overdosed in the sense that too many 0098 consecutive empty lines make the code harder to follow. 0099 0100 Lines containing only whitespace are considered to be empty in this 0101 context. 0102 0103 **Recognized parameters:** 0104 0105 Name Default Description 0106 ------------------------------- --------- -------------------------------------------- 0107 max-consecutive-empty-lines 2 Maximum number of consecutive empty lines. 0108 0109 **Compliance:** Inspirel 0110 0111 0112 L006 Source file should not be too long 0113 --------------------------------------- 0114 0115 The source file should not exceed a *reasonable* length. 0116 0117 Long source files can indicate an opportunity for refactoring. 0118 0119 **Recognized parameters:** 0120 0121 Name Default Description 0122 ------------------- --------- ------------------------------------ 0123 max-file-length 2000 Maximum number of lines in a file. 0124 0125 **Compliance:** Inspirel 0126 0127 0128 T001 One-line comments should not have forced continuation 0129 ---------------------------------------------------------- 0130 0131 The one-line comment is a comment that starts with `//`. 0132 0133 The usual intent is to let the comment continue till the end of the 0134 line, but the preprocessing rules of the language allow to actually 0135 continue the comment in the next line if *line-splicing* is forced with 0136 the backslash at the end of the line: 0137 0138 ~~~~ 0139 void foo() 0140 { 0141 // this comment is continued in the next line \ 0142 exit(0); 0143 } 0144 ~~~~ 0145 0146 It is not immediately obvious what happens in this example. Moreover, 0147 the line-splicing works only if the backslash is really the last 0148 character in the line - which is error prone because any white 0149 characters that might appear after the backslash will change the meaning 0150 of the program without being visible in the code. 0151 0152 **Compliance:** Inspirel 0153 0154 0155 T002 Reserved names should not be used for preprocessor macros 0156 -------------------------------------------------------------- 0157 0158 The C++ Standard reserves some forms of names for language 0159 implementations. One of the most frequent violations is a definition of 0160 preprocessor macro that begins with underscore followed by a capital 0161 letter or containing two consecutive underscores: 0162 0163 ~~~~ 0164 #define _MY_MACRO something 0165 #define MY__MACRO something 0166 ~~~~ 0167 0168 Even though the majority of known compilers use more obscure names for 0169 internal purposes and the above code is not likely to cause any 0170 significant problems, all such names are *formally reserved* and 0171 therefore should not be used. 0172 0173 Apart from the use of underscore in macro names, preprocessor macros 0174 should not be used to redefine language keywords: 0175 0176 ~~~~ 0177 #define private public 0178 #define const 0179 ~~~~ 0180 0181 **Compliance:** ISO 0182 0183 0184 T003 Some keywords should be followed by a single space 0185 ------------------------------------------------------- 0186 0187 Keywords from the following list: 0188 0189 - `case` 0190 - `class` 0191 - `delete` 0192 - `enum` 0193 - `explicit` 0194 - `extern` 0195 - `goto` 0196 - `new` 0197 - `struct` 0198 - `union` 0199 - `using` 0200 0201 should be followed by a single space for better readability. 0202 0203 **Compliance:** Inspirel 0204 0205 0206 T004 Some keywords should be immediately followed by a colon 0207 ------------------------------------------------------------ 0208 0209 Keywords from the following list: 0210 0211 - `default` 0212 - `private` 0213 - `protected` 0214 - `public` 0215 0216 should be immediately followed by a colon, unless used in the list of 0217 base classes: 0218 0219 ~~~~ 0220 class A : public B, private C 0221 { 0222 public: 0223 A(); 0224 ~A(); 0225 protected: 0226 // ... 0227 private: 0228 // ... 0229 }; 0230 0231 void fun(int a) 0232 { 0233 switch (a) 0234 { 0235 // ... 0236 default: 0237 exit(0); 0238 } 0239 } 0240 ~~~~ 0241 0242 **Compliance:** Inspirel 0243 0244 0245 T005 Keywords break and continue should be immediately followed by a semicolon 0246 ------------------------------------------------------------------------------ 0247 0248 The `break` and `continue` keywords should 0249 be immediately followed by a semicolon, with no other tokens in between: 0250 0251 ~~~~ {.example} 0252 while (...) 0253 { 0254 if (...) 0255 { 0256 break; 0257 } 0258 if (...) 0259 { 0260 continue; 0261 } 0262 // ... 0263 } 0264 ~~~~ 0265 0266 **Compliance:** Inspirel 0267 0268 0269 T006 Keywords return and throw should be immediately followed by a semicolon or a single space 0270 ---------------------------------------------------------------------------------------------- 0271 0272 The `return` and `throw` keywords should be 0273 immediately followed by a semicolon or a single space: 0274 0275 ~~~~ {.example} 0276 void fun() 0277 { 0278 if (...) 0279 { 0280 return; 0281 } 0282 // ... 0283 } 0284 0285 int add(int a, int b) 0286 { 0287 return a + b; 0288 } 0289 ~~~~ 0290 0291 An exception to this rule is allowed for exeption specifications: 0292 0293 ~~~~ {.example} 0294 void fun() throw(); 0295 ~~~~ 0296 0297 **Compliance:** Inspirel 0298 0299 0300 T007 Semicolons should not be isolated by spaces or comments from the rest of the code 0301 -------------------------------------------------------------------------------------- 0302 0303 The semicolon should not stand isolated by whitespace or comments from 0304 the rest of the code. 0305 0306 ~~~~ {.example} 0307 int a ; // bad 0308 int b 0309 ; // bad 0310 int c; // OK 0311 ~~~~ 0312 0313 As an exception from this rule, semicolons surrounded by spaces are 0314 allowed in `for` loops: 0315 0316 ~~~~ {.example} 0317 for ( ; ; ) // OK as an exception 0318 { 0319 // ... 0320 } 0321 ~~~~ 0322 0323 **Compliance:** Inspirel 0324 0325 0326 T008 Keywords catch, for, if, switch and while should be followed by a single space 0327 ----------------------------------------------------------------------------------- 0328 0329 Keywords `catch`, `for`, `if`, 0330 `switch` and `while` should be followed by a 0331 single space and then an opening left parenthesis: 0332 0333 ~~~~ {.example} 0334 catch (...) 0335 { 0336 for (int i = 0; i != 10; ++i) 0337 { 0338 if (foo(i)) 0339 { 0340 while (getline(cin, line)) 0341 { 0342 switch (i % 3) 0343 { 0344 case 0: 0345 bar(line); 0346 break; 0347 // ... 0348 } 0349 } 0350 } 0351 } 0352 } 0353 ~~~~ 0354 0355 **Compliance:** Inspirel 0356 0357 0358 T009 Comma should not be preceded by whitespace, but should be followed by one 0359 ------------------------------------------------------------------------------ 0360 0361 A comma, whether used as operator or in various lists, should not be 0362 preceded by whitespace on its left side, but should be followed by 0363 whitespace on its right side: 0364 0365 ~~~~ {.example} 0366 void fun(int x, int y, int z); 0367 int a[] = {5, 6, 7}; 0368 class A : public B, 0369 public C 0370 { 0371 // ... 0372 }; 0373 ~~~~ 0374 0375 An exception to this rule is allowed for `operator,`: 0376 0377 ~~~~ {.example} 0378 struct A {}; 0379 void operator,(const A &left, const A &right); 0380 ~~~~ 0381 0382 **Compliance:** Inspirel 0383 0384 0385 T010 Identifiers should not be composed of 'l' and 'O' characters only 0386 ---------------------------------------------------------------------- 0387 0388 The characters 'l' (which is lowercase 'L') and 'O' (which is uppercase 0389 'o') should not be the only characters used in the identifier, because 0390 this would make them visually similar to numeric literals. 0391 0392 **Compliance:** Inspirel 0393 0394 0395 T011 Curly brackets from the same pair should be either in the same line or in the same column 0396 ---------------------------------------------------------------------------------------------- 0397 0398 Corresponding curly brackets should be either in the same line or in 0399 the same column. This promotes clarity by emphasising scopes, but 0400 allows concise style of one-line definitions and empty blocks: 0401 0402 ~~~~ {.example} 0403 class MyException {}; 0404 0405 struct MyPair 0406 { 0407 int a; 0408 int b; 0409 }; 0410 0411 enum state { close, open }; 0412 0413 enum colors 0414 { 0415 black, 0416 red, 0417 green, 0418 blue, 0419 white 0420 }; 0421 ~~~~ 0422 0423 **Compliance:** Inspirel 0424 0425 0426 T012 Negation operator should not be used in its short form 0427 ----------------------------------------------------------- 0428 0429 The negation operator (exclamation mark) reduces readability of the code 0430 due to its terseness. Prefer explicit logical comparisons or alternative 0431 tokens for increased readability: 0432 0433 ~~~~ {.example} 0434 if (!cond) // error-prone 0435 if (cond == false) // better 0436 if (not cond) // better (alternative keyword) 0437 ~~~~ 0438 0439 **Compliance:** Inspirel 0440 0441 0442 T013 Source files should contain the copyright notice 0443 ----------------------------------------------------- 0444 0445 The copyright notice is required by man coding standards and guidelines. 0446 In some countries every written artwork has some copyright, even if 0447 implicit. Prefer explicit notice to avoid any later confusion. 0448 0449 This rule verifies that at least one comment in the source file contains 0450 the "copyright" word. 0451 0452 **Compliance:** Boost 0453 0454 0455 T014 Source files should refer the Boost Software License 0456 --------------------------------------------------------- 0457 0458 The Boost Software License should be referenced in the source code. 0459 0460 This rule verifies that at least one comment in the source file contains 0461 the "Boost Software License" phrase. 0462 0463 Note that this rule is very specific to the Boost libraries and those 0464 project that choose to use the Boost license. It is therefore not part 0465 of the default profile. 0466 0467 **Compliance:** Boost 0468 0469 0470 T015 HTML links in comments and string literals should be correct 0471 ----------------------------------------------------------------- 0472 0473 The links embedded in comments and string literals should have correct 0474 form and should reference existing files. 0475 0476 **Compliance:** Boost 0477 0478 0479 T016 Calls to min/max should be protected against accidental macro substitution 0480 ------------------------------------------------------------------------------- 0481 0482 The calls to min and max functions should be protected against 0483 accidental macro substitution. 0484 0485 ~~~~ {.example} 0486 x = max(y, z); // wrong, vulnerable to accidental macro substitution 0487 0488 x = (max)(y, z); // OK 0489 0490 x = max BOOST_PREVENT_MACRO_SUBSTITUTION (y, z); // OK 0491 ~~~~ 0492 0493 **Compliance:** Boost 0494 0495 0496 T017 Unnamed namespaces are not allowed in header files 0497 ------------------------------------------------------- 0498 0499 Unnamed namespaces are not allowed in header files. 0500 0501 The typical use of unnamed namespace is to hide module-internal names 0502 from the outside world. Header files are physically concatenated in a 0503 single translation unit, which logically merges all namespaces with the 0504 same name. Unnamed namespaces are also merged in this process, which 0505 effectively undermines their initial purpose. 0506 0507 Use named namespaces in header files. Unnamed namespaces are allowed in 0508 implementation files only. 0509 0510 **Compliance:** Boost 0511 0512 0513 T018 Using namespace is not allowed in header files 0514 --------------------------------------------------- 0515 0516 Using namespace directives are not allowed in header files. 0517 0518 The using namespace directive imports names from the given namespace and 0519 when used in a header file influences the global namespace of all the 0520 files that directly or indirectly include this header file. 0521 0522 It is imaginable to use the using namespace directive in a limited scope 0523 in a header file (for example in a template or inline function 0524 definition), but for the sake of consistency this is also discouraged. 0525 0526 **Compliance:** C++ Coding Standards 0527 0528 0529 T019 Control structures should have complete curly-braced block of code 0530 ----------------------------------------------------------------------- 0531 0532 Control structures managed by for, if and while constructs can be 0533 associated with a single instruction or with a complex block of code. 0534 Standardizing on the curly-braced blocks in all cases allows one to 0535 avoid common pitfalls and makes the code visually more uniform. 0536 0537 ~~~~ {.example} 0538 if (x) foo(); // bad style 0539 if (x) { foo(); } // OK 0540 0541 if (x) 0542 foo(); // again bad style 0543 0544 if (x) 0545 { // OK 0546 foo(); 0547 } 0548 0549 if (x) 0550 while (y) // bad style 0551 foo(); // bad style 0552 0553 if (x) 0554 { // OK 0555 while (y) 0556 { // OK 0557 foo(); 0558 } 0559 } 0560 0561 for (int i = 0; i <= 10; ++i); // oops! 0562 cout << "Hello\n"; 0563 0564 for (int i = 0; i <= 10; ++i) // OK 0565 { 0566 cout << "Hello\n"; 0567 } 0568 ~~~~ 0569 0570 **Compliance:** Inspirel