Format and Style

中文

Format and Style
Naming Conventions
Comment Conventions

Indentation and Line Breaks

Only use 4 spaces for code indentation, tabs are forbidden.
Keep each line of code within 120 characters, break lines and indent the next line by 4 spaces if exceeded.

Curly braces { and } should each be on their own line. For example:

if (condition)  
{
    do_something();
}

void func(void)  
{
    ...
}
```

Spaces and Empty Lines

Add a space on each side of operators, without spaces for pre/post increment/decrement. For example:
```
x = 1;
a + b; 
i++;
```
```
Add a space after commas. For example:
```
void foo(int a, char b);
```
```

Header Files

Use the _FILE_H_ macro to avoid duplicate includes.
Import headers in alphabetical order, with library headers first. Use <> for library headers and "" for other headers. For example:
```
#include <stdlib.h>    
#include <stdio.h>
#include "bar.h"
#include "foo.h"
```
```

Naming Conventions

Types

Enum types are all lowercase with underscores, enum constants start with uppercase. For example:

enum color_type
{
    Red,  
    Green,
    Blue,
    Light_Pink,
};
```

Structures, unions and typedefs are lowercase with underscores. For example:

struct foo
{
    char *name;
    union coordinate
    {
        int x;
        int y; 
    }
};
```

Functions and Variables

Function names are lowercase with underscores. For example:

void do_something(int arg1, char arg2)
{
    ...
}
```

Functions should be block written by modules, with comments for large blocks that cannot be easily understood through code. Returning values without special meaning can be adjacent to other blocks, otherwise they should be single blocks.
Variable names are lowercase with underscores. For example:
```
int num_times;
char *pointer;
```
```
Macro names are all uppercase with underscores. User configurable macros should have CFG prefix. For example:
```
#define MR_CFG_OBJECT_NAME_SIZE      15
```
```
Typedefs use the type name with _t suffix (avoid for structs/pointers for clarity). For example:
```
typedef unsigned int uint32_t;
```
```

Variables should have clear meaning when used. For pointers without writes, convert to variables. For example:

void func(int *args) 
{
    /* Convert to avoid accidental overwrite */
    int value = *args;
    printf("%d\n", value);
}
```

File Names

File names are lowercase with underscores, no uppercase letters, config files end with config. For example:
```
foo_bar.c
test_case.h
mrconfig.h
```
```

Macros

Macro names are ALL_CAPS with underscores, user configurable macros have CFG prefix. For example:
```
#define MR_CFG_OBJECT_NAME_SIZE      15
```
```

Comment Conventions

Single line comments use /* */, multi-line comments:

/**
 * Multi-line comment 
 * Second line
 */

Function comments use Doxygen style:

/**
 * @brief This function registers a device.
 *
 * @param dev The device. 
 * @param name The name of the device.
 * @param type The type of the device.
 * @param sflags The support flags of the device.
 * @param ops The operations of the device.
 * @param drv The driver of the device.
 *
 * @return MR_EOK on success, otherwise an error code.
 */
```

Structs, macros etc need comments:

/**
* @brief Driver structure.
*/
struct mr_drv
{
   uint32_t type;                                                  /**< Device type */
   void *ops;                                                      /**< Driver operations */
   void *data;                                                     /**< Driver data */
};

/**
* @brief Null pointer.
*/
#define MR_NULL                      (void *)0

Function declarations need comments to include all similar functions:

/**
 * @addtogroup Device description
 * @{
 */
int mr_dev_open(const char *name, uint32_t oflags); 
int mr_dev_close(int desc);
ssize_t mr_dev_read(int desc, void *buf, size_t size);
ssize_t mr_dev_write(int desc, const void *buf, size_t size);
int mr_dev_ioctl(int desc, int cmd, void *args);
/** @} */

4.9 KiB Raw Blame History