documentation:coding_practices
=>  Releases

Current version
Git/Latestdiff: 1.5.6

Latest Snapshots
Produced after each commit or rebase to new upstream version

GIT
RSBAC source code, can be unstable sometimes

=>  Events

No events planned

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

documentation:coding_practices [2005/11/22 13:12]
kang spelling
documentation:coding_practices [2006/05/02 15:40]
Line 1: Line 1:
-First rule is: 
-You should not write code for yourself. If you do, no one will be able to work on your project. Code should be clear and concise at all time. Functionality should not be duplicated. Comments should be sharp and precise when possible. 
  
-General kernel rules are, no more than 10 variables per function, no more than 2 or 3 console screens of text per function (except switch..case),​ no more than 3 levels of indentation. 
-Of course this may not always be applicable, but when you reach any of thoses values you can start checking if there is not something you could have made simpler :) 
- 
-===== Indent ===== 
- 
-"​linux/​rsbac"​ and "​linux/​include/​rsbac"​ have been re-indented with "​indent -kr -i8", which after several tests seemed to be the best compromise. However, due to the previous space-based indentation which was different in some parts of the source code, and only 2 spaces, many functions or code alignement (especially when there is 10 levels of indentation,​ *cough*) have been visually messed up. 
- 
-While I fixed most, over so many lines of code its impossible to do in a few days. If you find something wrong, and there are probably many places where it is, please, please fix it. It takes only a few mins when you see it vs hours and hours when doing all files, as this can't be automated properly. 
- 
-===== Comments ===== 
- 
-  * No reason to tell what file we are in, its written on the editor, and we know when we're at the last line ! 
-**Wrong** 
-<​code>​ 
-File lala.c 
-.... 
-... 
-/* end of file lala.c */ 
-</​code>​ 
- 
-  * No inline comments, its hard to read when you read millions of lines a day 
-**Wrong** 
-<​code>​ 
-... 
-if(!lala) { /* check if lala is right */ 
-</​code>​ 
- 
-**Right** 
-<​code>​ 
-... 
-/* check if lala is right */ 
-if(!lala) { 
-... 
-</​code>​ 
- 
- * No reason to make end of functions/​if/​etc in **most** cases 
-**Wrong** 
-<​code>​ 
-#ifdef CONFIG_BLAH 
-... 
-... 
-#endif /* end CONFIG_BLAH */ 
-</​code>​ 
-If your code is full of endif}}}}}}} then it should be rewritten :) 
-Ok, sarcasms apart, in most case its easy to see or to push "​%"​ (or equivalent in non-vim editors) to see where the ifdef is from. For functions, your editor should tell you in which function you are and in which sub-bracket you are. 
-Please dont use thoses too much. 
- 
-  * Do not comment without reason. Why commenting when there is NO need to ? 
-**Wrong** 
-<​code>​ 
-/* MAC */ 
-#ifdef CONFIG_RSBAC_MAC 
-(three lines of code) 
-#endif /* end MAC */ 
-</​code>​ 
- 
- 
-  * Never describe what your line of code does. We can read. Tell what the function is for, instead, and only comment tricky hacks. 
-**Wrong** 
-<​code>​ 
-/* No perm? Failure */ 
-return -EPERM; 
-</​code>​ 
- 
- 
-  * Try to make nice code blocks :) 
-**Right** 
-<​code>​ 
-/*  Blablablabla 
- ​* ​ lalalalal 
- ​* ​ llulu 
- */ 
-</​code>​ 
- 
-This is much more readable and scales on any tab size, doesn'​t needs spaces, than: 
-**Wrong** 
-<​code>​ 
-/* blab */ 
-/* lalalalaal */ 
-/* llulslu */ 
-</​code>​ 
- 
-  * Do not use separators with comments, if you have to use it then your code is really too complex. (Actually I've only seen some to separate functions. Well! Functions are already separated.) The only time it looks ok is for example, when explaining the separation and that it really indicates something. 
-**Wrong** 
-<​code>​ 
-blala() { 
-... 
-} 
- 
-/*********/ 
- 
-lili() { 
-... 
-} 
-</​code>​ 
- 
-**Acceptable** 
-<​code>​ 
-blala() { 
-... 
-} 
- 
-/* lili_* are functions visible from userspace */ 
- 
-lili_hm() { 
-... 
-} 
- 
-lili_ah() { 
-</​code>​ 
- 
-  * We know what declarations are (especially when empty..:) 
-**Wrong** 
-<​code>​ 
-/​******************************************/​ 
-/*   ​DECLARATIONS ​                        */ 
-/​******************************************/​ 
- 
-/​******************************************/​ 
-/*   ​CODE ​                                */ 
-/​******************************************/​ 
-</​code>​ 
-**Right** 
-<​code>​ 
-int lala=0; 
-rsbac_lala *la; 
-.. 
- 
-myfunct.. 
-</​code>​ 
- 
-===== Factorizing ===== 
- 
-Refactoring is the process of taking repetitive code out of the current function and to make a new one. All code should not be refactorized,​ however, so don't over-factorize,​ but it is usually a good thing: 
-  * Reduces the code size, the number of lines to read, ... 
-  * Make things easy: changes are only in __one__ place instead of 10 (and forgetting the 11th) 
-  * People who didn't write the code do not know where the code has been duplicated. They will probably miss it. 
-  * It enhance syour coding speed ! Less typing, less checking ! 
- 
- 
-===== Syntax ===== 
-The kernel syntax is k&r style. 
- 
-<​code>​ 
-/* No indent before ifdefs */ 
-if(xxx) { 
-#ifdef CONFIG_RSBAC 
-    rsbac_hello_func();​ 
-#endif 
- 
-/* Tabs are made for indenting, spaces are for 
- * formatting comments if ever                 ​needed :) 
- ​*/ ​ 
- 
-/* Iteration */ 
-if() { 
-... 
-} 
-while() { 
-... 
-} 
- 
-/* Function */ 
-rsbac_moin () 
-{ 
-... 
-} 
-</​code>​ 
- 
-If this document is not 100% correct or complete feel free to modify it! 
//
documentation/coding_practices.txt · Last modified: 2006/05/02 15:40 (external edit)

documentation/coding_practices.txt · Last modified: 2006/05/02 15:40 (external edit)
This website is kindly hosted by m-privacy