Difference between revisions of "Coding Style"

From ReactOS Wiki
Jump to: navigation, search
(Categories)
m
Line 12: Line 12:
 
The usual source code file consists of the following parts (some sections can be omitted if they are empty):
 
The usual source code file consists of the following parts (some sections can be omitted if they are empty):
 
* The header (an example)
 
* The header (an example)
 +
<syntaxhighlight lang="c">
 
  /*
 
  /*
 
   * PROJECT:        ReactOS Kernel
 
   * PROJECT:        ReactOS Kernel
Line 22: Line 23:
 
   *                  Thomas Weidenmueller (w3seek@reactos.org)
 
   *                  Thomas Weidenmueller (w3seek@reactos.org)
 
   */
 
   */
 +
</syntaxhighlight>
 
* Includes section, which has all #include statements, and vital defines (like #define NDEBUG)
 
* Includes section, which has all #include statements, and vital defines (like #define NDEBUG)
 +
<syntaxhighlight lang="c">
 
  /* INCLUDES ******************************************************************/
 
  /* INCLUDES ******************************************************************/
 +
</syntaxhighlight>
 
* Defines section, for per-file defines
 
* Defines section, for per-file defines
 +
<syntaxhighlight lang="c">
 
  /* DEFINES *******************************************************************/
 
  /* DEFINES *******************************************************************/
 +
</syntaxhighlight>
 
* Private (not exported, or used only within the scope of this file) functions
 
* Private (not exported, or used only within the scope of this file) functions
 +
<syntaxhighlight lang="c">
 
  /* PRIVATE FUNCTIONS ******************************************************/
 
  /* PRIVATE FUNCTIONS ******************************************************/
 +
</syntaxhighlight>
 
* Public functions (if it's a DLL, or a driver)
 
* Public functions (if it's a DLL, or a driver)
 +
<syntaxhighlight lang="c">
 
  /* PUBLIC FUNCTIONS **********************************************************/
 
  /* PUBLIC FUNCTIONS **********************************************************/
 +
</syntaxhighlight>
 
* Or just this way, if it's a standalone app
 
* Or just this way, if it's a standalone app
 +
<syntaxhighlight lang="c">
 
  /* FUNCTIONS *****************************************************************/
 
  /* FUNCTIONS *****************************************************************/
 +
</syntaxhighlight>
 
* [OPTIONAL?]File ends with
 
* [OPTIONAL?]File ends with
 +
<syntaxhighlight lang="c">
 
  /* EOF */<NewLineCharacterOnYourPlatform>
 
  /* EOF */<NewLineCharacterOnYourPlatform>
 +
</syntaxhighlight>
  
 
== The Rules ==  
 
== The Rules ==  
Line 47: Line 61:
 
* Generic note about TABs usage: Don't use TABs for formatting; use TABs for indenting only and use only spaces for formatting
 
* Generic note about TABs usage: Don't use TABs for formatting; use TABs for indenting only and use only spaces for formatting
 
Example:
 
Example:
 +
<syntaxhighlight lang="c">
 
  NTSTATUS
 
  NTSTATUS
 
  SomeApi(IN Type Param1,
 
  SomeApi(IN Type Param1,
Line 58: Line 73:
 
  [TAB][TAB]CallSomeFunc();
 
  [TAB][TAB]CallSomeFunc();
 
  ...
 
  ...
 
+
</syntaxhighlight>
 
* Unfortunately if the code is shared with WINE, it isn't possible to use // comments, /*...*/ must always be used
 
* Unfortunately if the code is shared with WINE, it isn't possible to use // comments, /*...*/ must always be used
 
* Example of standard API header, please don't make up your own until really necessary:
 
* Example of standard API header, please don't make up your own until really necessary:
Line 83: Line 98:
 
   STDCALL
 
   STDCALL
 
   SomeAPI( ...
 
   SomeAPI( ...
 
+
</syntaxhighlight>
 
== Astyle for kernel code ==
 
== Astyle for kernel code ==
  

Revision as of 12:49, 6 March 2013

The ReactOS Project currently enforces very few rules for coding style.

Generic ideas whether and how to apply formatting

  • When hacking on existing code follow the existing style rather than reformat
  • If reformatting to the generic coding style:
    • never mix code changes and formatting
    • say clear in commit message that you change formatting only (like [FORMATTING])
  • Don't reformat shared code (with Wine or other projects), it's hard to merge changes into reformatted code

Source code file structure

The usual source code file consists of the following parts (some sections can be omitted if they are empty):

  • The header (an example)
 /*
  * PROJECT:         ReactOS Kernel
  * LICENSE:         GPL - See COPYING in the top level directory
  * FILE:            ntoskrnl/ob/namespce.c
  * PURPOSE:         Manages all functions related to the Object Manager name-
  *                  space, such as finding objects or querying their names.
  * PROGRAMMERS:     Alex Ionescu (alex.ionescu@reactos.org)
  *                  Eric Kohl
  *                  Thomas Weidenmueller (w3seek@reactos.org)
  */
  • Includes section, which has all #include statements, and vital defines (like #define NDEBUG)
 /* INCLUDES ******************************************************************/
  • Defines section, for per-file defines
 /* DEFINES *******************************************************************/
  • Private (not exported, or used only within the scope of this file) functions
 /* PRIVATE FUNCTIONS ******************************************************/
  • Public functions (if it's a DLL, or a driver)
 /* PUBLIC FUNCTIONS **********************************************************/
  • Or just this way, if it's a standalone app
 /* FUNCTIONS *****************************************************************/
  • [OPTIONAL?]File ends with
 /* EOF */<NewLineCharacterOnYourPlatform>

The Rules

  • When a line with function call is less than 80 chars long, params should be written on the same line
  • When a line with function call is more than 80 chars long (because calling func has many params), it maybe wise to write params as column, writing comments for each param (when it is needed)
  • {} must be on its own line, they must be aligned to the beginning of previous statement, statements inside {} are indented
  • [NOT STRICT] Don't use {} if only one statement is enclosed in it (except when comments like /* TODO */ or /* FIXME */ or DPRINTs are included also)
  • TABs vs. Spaces:
    • Kernel is strictly Spaces-only
    • .rbuild files are strictly TABs-only
    • When editing other modules, either obey the style, or do a conversion to one style (which results in fewer changes of tabs->spaces or vice versa).
  • Generic note about TABs usage: Don't use TABs for formatting; use TABs for indenting only and use only spaces for formatting

Example:

 NTSTATUS
 SomeApi(IN Type Param1,
 [spaces]IN Type Param2)
 {
 [TAB]ULONG MyVar;
 [TAB]MyVar = 0;
 [TAB]if ((MyVar == 3) &&
 [TAB][sp](Param1 == TRUE))
 [TAB]{
 [TAB][TAB]CallSomeFunc();
 ...
  • Unfortunately if the code is shared with WINE, it isn't possible to use // comments, /*...*/ must always be used
  • Example of standard API header, please don't make up your own until really necessary:
 /*++
 * @name SomeAPI
 * @implemented NT4
 *
 * Do nothing for 500ms.
 *
 * @param SomeParameter
 *        Description of the parameter. Wrapped to more lines on ~70th
 *        column.
 *
 * @param YetAnotherParameter
 *        Bleh, bleh :)
 *
 * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
 *         othwerwise.
 *
 * @remarks Must be called at IRQL == DISPATCH_LEVEL
 *
 *--*/
 NTSTATUS
 STDCALL
 SomeAPI( ...

</syntaxhighlight>

Astyle for kernel code

astyle -b -c -y --style=ansi --mode=c $FILE

Text Editors

  • Notepad (GvG), problem is tab always == 8 spaces
  • Syn (w3seek), problem is tabs again
  • Eclipse (w3seek), like the same
  • Ultraedit on windows (hpoussin), indenting blank lines
  • vi on unix (tinus)
  • Crimson Editor (Ged) no known problems
  • VS 2k3 (Brandon), Don't know any problems. I like using tabs. Willing to change if need be.

See Also