编码风格

本文描述了通用编码风格指南,应该用于新ReactOS代码。 这些指导原则只适用于C和c++源文件。 ReactOS同意本文档的成员在2013年10月的会议。

尽可能多的现有ReactOS代码应该转化为这种风格,除非有理由反对这样做(比如如果代码是在不久的将来将会重写)。 看到 笔记格式修改现有代码 为更多的细节。

代码同步其他来源(如葡萄酒)不能被重写。


文件结构

  1. 每个ReactOS源代码文件应该包含这样一个文件头:

    /*  * PROJECT:        ReactOS Kernel  * LICENSE:        GNU GPLv2 only as published by the Free Software Foundation  * PURPOSE:        Does cool things like ...  * PROGRAMMERS:    Arno Nymous (abc@mailaddress.com)  *                 Mike Blablabla (mike@blabla.com)  */

    我们需要保持一定程度的一致性,确保许可证可惟一地识别。 记住一些许可证可能ReactOS-specific。 因此,请使用一个精确的名称授权和提供信息来获取它。

    例子:

    你可以自己添加到 程序员 节的文件如果你做了一个重大贡献,可以负责整个文件或其中的一部分。

    • GNU GPLv2由自由软件基金会发布

    • GNU GPLv2或任何由自由软件基金会发布版本

    • BSD -复制。 手臂在顶级目录中

  2. 使用标题与下面的一个功能:

    /**  * @name SomeAPI  * @implemented  *  * Do nothing for 500ms.  *  * @param SomeParameter  * Description of the parameter.  *  * @param YetAnotherParameter  * Bleh, bleh :)  *  * @return  * STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL  * otherwise.  *  * @remarks Must be called at IRQL == DISPATCH_LEVEL  *  */

缩进

  1. 缩进4空间,不使用标签!

  2. 缩进一个标签和一个switch语句的case语句。

    正确的:

    switch (Condition) {     case 1:         DoSomething();         break; }

    错误的:

    switch (Condition) { case 1:      DoSomething();      break; }

间距

  1. 不要使用空格在一元操作符。
    正确的: 我+ +;
    错误的: 我+ +;

  2. 在二元和三元运算符的空间。
    正确的: a = b + c;
    错误的: a = b + c;

  3. 没有地方空间在逗号和分号。

    正确的:

    for (int i = 0; i < 5; i++)     DoSomething();   func1(a, b);

    错误的:

    for (int i = 0 ; i < 5 ; i++)     DoSomething();   func1(a , b) ;

  4. 控制语句和括号之间的空格。

    正确的:

    if (Condition)     DoSomething();

    错误的:

    if(Condition)     DoSomething();

  5. 不会将空间功能及其之间的括号,括号之间或和其内容。

    正确的:

    func(a, b);

    错误的:

    func (a, b); func( a, b );

线断裂

  1. 每个语句应该得到自己的线。

    正确的:

    x++; y++;   if (Condition)     DoSomething();

    错误的:

    x++; y++;   if (Condition) DoSomething();

牙套

  1. 总是把括号( { } )在自己的台词。

  2. 一行控制条款可以使用括号,但这不是一个要求。 一个例外是一行控制条款包括额外的评论。

    正确的:

    if (Condition)     DoSomething();   if (Condition) {     DoSomething(); }   if (Condition) {     // This is a comment     DoSomething(); }   if (Condition)     DoSomething(); else     DoSomethingElse();   if (Condition) {     DoSomething(); } else {     DoSomethingElse();     YetAnother(); }

    错误的:

    if (Condition) {     DoSomething(); }   if (Condition)     // This is a comment     DoSomething();   if (Condition)     DoSomething(); else {     DoSomethingElse();     YetAnother(); }

控制结构

  1. 不要使用逆逻辑控制条款。
    正确的: 如果(i = = 1)
    错误的: 如果(1 = =)

  2. 避免太多的级联控制结构水平。 更喜欢“线性风格”“树风格”。 使用 转到 当它有助于使代码更清洁的(例如清理道路)。

    正确的:

    if (!func1())     return;   i = func2(); if (i == 0)     return;   j = func3(); if (j == 1)     return; …

    错误的:

    if (func1()) {     i = func2();     if (func2())     {         j = func3();         if (func3())         {             …         }     } }

命名

  1. 利用变量和函数的名称。
    匈牙利命名法 可能在开发用于Win32,但它不是必需的。 如果你不使用它,一个名字的第一个字母必须大写(没有camelCase)。 不要使用下划线作为分隔符。

    正确的:

    PLIST_ENTRY FirstEntry; VOID NTAPI IopDeleteIoCompletion(PVOID ObjectBody); PWSTR pwszTest;

    错误的:

    PLIST_ENTRY first_entry; VOID NTAPI iop_delete_io_completion(PVOID objectBody); PWSTR pwsztest;

  2. 避免使用函数和变量名称缩写,尽可能使用描述性动词。

  3. 布尔值之前有意义的动词“是”和“做”如果可能的话,如果它符合使用。

    正确的:

    BOOLEAN IsValid; BOOLEAN DidSendData;

    错误的:

    BOOLEAN Valid; BOOLEAN SentData;

评论

  1. 避免line-wasting评论,这可能适合一行。

    正确的:

    // This is a one-line comment   /* This is a C-style comment */   // // This is a comment over multiple lines. // We don’t define any strict rules for it. //

    错误的:

    // // This comment wastes two lines //

空,虚假和0

  1. 空指针应该写成
    在罕见的情况下,您的环境建议另一个空指针(例如c++ 11 nullptr ),当然你可以使用这个。 只是不使用价值 0

  2. Win32 / NT布尔值应该写成 真正的
    在罕见的情况下,使用C / c++ bool 变量,你应该把它们写成 真正的

笔记格式修改现有代码

  • 从来没有完全格式化文件并将代码更改。 这样做在单独提交。

  • 如果提交只包含格式变化,说这显然之前的提交消息 (格式)





Coding Style

This  article describes general coding style guidelines, which should be used  for new ReactOS code. These guidelines apply exclusively to C and C++  source files. The Members of ReactOS agreed on this document in the  October 2013 meeting.

As much existing ReactOS code as possible should be converted to  this style unless there are reasons against doing this (like if the code  is going to be rewritten from scratch in the near future). See Notes on reformatting existing code for more details.

Code synchronized with other sources (like Wine) must not be rewritten.

Contents

1 File Structure

2 Indentation

3 Spacing

4 Line breaking

5 Braces

6 Control structures

7 Naming

8 Commenting

9 Null, false and 0

10 Notes on reformatting existing code

11 Using an automatic code style tool

12 Points deliberately left out

13 See also

File Structure

Every ReactOS source code file should include a file header like this:

/*  * PROJECT:        ReactOS Kernel  * LICENSE:        GNU GPLv2 only as published by the Free Software Foundation  * PURPOSE:        Does cool things like ...  * PROGRAMMERS:    Arno Nymous (abc@mailaddress.com)  *                 Mike Blablabla (mike@blabla.com)  */

We need to keep some consistency and ensure that licenses can be  identified uniquely. Keep in mind that some licenses may be  ReactOS-specific. Therefore, please use a precise name for the license  and give information where to obtain it.

Examples:

You may add yourself to the PROGRAMMERS section of a file if you did a major contribution to it and could take responsibility for the whole file or a part of it.

GNU GPLv2 only as published by the Free Software Foundation

GNU GPLv2 or any later version as published by the Free Software Foundation

BSD – See COPYING.ARM in the top-level directory

Use a header comparable to the following one for functions:

/**  * @name SomeAPI  * @implemented  *  * Do nothing for 500ms.  *  * @param SomeParameter  * Description of the parameter.  *  * @param YetAnotherParameter  * Bleh, bleh :)  *  * @return  * STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL  * otherwise.  *  * @remarks Must be called at IRQL == DISPATCH_LEVEL  *  */

Indentation

Indent with 4 spaces, don’t use tabs!

Indent both a case label and the case statement of a switch statement.

Right:

switch (Condition) {     case 1:         DoSomething();         break; }

Wrong:

switch (Condition) { case 1:      DoSomething();      break; }

Spacing

Do not use spaces around unary operators.
Right: i++;
Wrong: i ++;

Place spaces around binary and ternary operators.
Right: a = b + c;
Wrong: a=b+c;

Do not place spaces before comma and semicolon.

Right:

for (int i = 0; i < 5; i++)     DoSomething();   func1(a, b);

Wrong:

for (int i = 0 ; i < 5 ; i++)     DoSomething();   func1(a , b) ;

Place spaces between control statements and their parentheses.

Right:

if (Condition)     DoSomething();

Wrong:

if(Condition)     DoSomething();

Do not place spaces between a function and its parentheses, or between a parenthesis and its content.

Right:

func(a, b);

Wrong:

func (a, b); func( a, b );

Line breaking

Each statement should get its own line.

Right:

x++; y++;   if (Condition)     DoSomething();

Wrong:

x++; y++;   if (Condition) DoSomething();

Braces

Always put braces ({ and }) on their own lines.

One-line control clauses may use braces, but this is not a  requirement. An exception are one-line control clauses including  additional comments.

Right:

if (Condition)     DoSomething();   if (Condition) {     DoSomething(); }   if (Condition) {     // This is a comment     DoSomething(); }   if (Condition)     DoSomething(); else     DoSomethingElse();   if (Condition) {     DoSomething(); } else {     DoSomethingElse();     YetAnother(); }

Wrong:

if (Condition) {     DoSomething(); }   if (Condition)     // This is a comment     DoSomething();   if (Condition)     DoSomething(); else {     DoSomethingElse();     YetAnother(); }

Control structures

Don’t use inverse logic in control clauses.
Right: if (i == 1)
Wrong: if (1 == i)

Avoid too many levels of cascaded control structures. Prefer a “linear style” over a “tree style”. Use goto when it helps to make the code cleaner (e.g. for cleanup pathes).

Right:

if (!func1())     return;   i = func2(); if (i == 0)     return;   j = func3(); if (j == 1)     return; …

Wrong:

if (func1()) {     i = func2();     if (func2())     {         j = func3();         if (func3())         {             …         }     } }

Naming

Capitalize names of variables and functions.
Hungarian Notation  may be used when developing for Win32, but it is not required. If you  don’t use it, the first letter of a name must be a capital too (no  camelCase). Do not use underscores as separators either.

Right:

PLIST_ENTRY FirstEntry; VOID NTAPI IopDeleteIoCompletion(PVOID ObjectBody); PWSTR pwszTest;

Wrong:

PLIST_ENTRY first_entry; VOID NTAPI iop_delete_io_completion(PVOID objectBody); PWSTR pwsztest;

Avoid abbreviating function and variable names, use descriptive verbs where possible.

Precede boolean values with meaningful verbs like "is" and "did" if possible and if it fits the usage.

Right:

BOOLEAN IsValid; BOOLEAN DidSendData;

Wrong:

BOOLEAN Valid; BOOLEAN SentData;

Commenting

Avoid line-wasting comments, which could fit into a single line.

Right:

// This is a one-line comment   /* This is a C-style comment */   // // This is a comment over multiple lines. // We don’t define any strict rules for it. //

Wrong:

// // This comment wastes two lines //

Null, false and 0

The null pointer should be written as NULL.
In the rare case that your environment recommends a different null pointer (e.g. C++11 nullptr), you may use this one of course. Just don’t use the value 0.

Win32/NT Boolean values should be written as TRUE and FALSE.
In the rare case that you use C/C++ bool variables, you should write them as true and false.

Notes on reformatting existing code

Never totally reformat a file and put a code change into it. Do this in separate commits.

If a commit only consists of formatting changes, say this clearly in the commit message by preceding it with [FORMATTING].