实用 | GitHub上一位老外的嵌入式C编码规范（收藏细读）

• 当宏使用多个语句时，使用do-while(0)语句保护它

typedef struct { int32_t px, py;
} point_t; point_t p; /* Define new point */ /* Wrong implementation */ /* Define macro to set point */ #define SET_POINT(p, x, y)  (p)->px = (x); (p)->py = (y) /* 2 statements. Last one should not implement semicolon */ SET_POINT(&p, 3, 4); /* Set point to position 3, 4. This evaluates to... */ (&p)->px = (3); (&p)->py = (4); /* ... to this. In this example this is not a problem. */ /* Consider this ugly code, however it is valid by C standard (not recommended) */ if (a) /* If a is true */ if (b) /* If b is true */ SET_POINT(&p, 3, 4);/* Set point to x = 3, y = 4 */ else SET_POINT(&p, 5, 6);/* Set point to x = 5, y = 6 */ /* Evaluates to code below. Do you see the problem? */ if (a) if (b)
        (&p)->px = (3); (&p)->py = (4); else (&p)->px = (5); (&p)->py = (6); /* Or if we rewrite it a little */ if (a) if (b)
        (&p)->px = (3);
        (&p)->py = (4); else (&p)->px = (5);
        (&p)->py = (6); /*
 * Ask yourself a question: To which `if` statement `else` keyword belongs?
 *
 * Based on first part of code, answer is straight-forward. To inner `if` statement when we check `b` condition
 * Actual answer: Compilation error as `else` belongs nowhere
 */ /* Better and correct implementation of macro */ #define SET_POINT(p, x, y)  do { (p)->px = (x); (p)->py = (y); } while (0) /* 2 statements. No semicolon after while loop */ /* Or even better */ #define SET_POINT(p, x, y)  do {    \ /* Backslash indicates statement continues in new line */ (p)->px = (x);                  \
    (p)->py = (y);                  \
} while (0) /* 2 statements. No semicolon after while loop */ /* Now original code evaluates to */ if (a) if (b) do { (&p)->px = (3); (&p)->py = (4); } while (0); else do { (&p)->px = (5); (&p)->py = (6); } while (0); /* Every part of `if` or `else` contains only `1` inner statement (do-while), hence this is valid evaluation */ /* To make code perfect, use brackets for every if-ifelse-else statements */ if (a) { /* If a is true */ if (b) { /* If b is true */ SET_POINT(&p, 3, 4);/* Set point to x = 3, y = 4 */ } else {
        SET_POINT(&p, 5, 6);/* Set point to x = 5, y = 6 */ }
}

/* OK */ #if defined(XYZ) #if defined(ABC) /* do when ABC defined */ #endif /* defined(ABC) */ #else /* defined(XYZ) */ /* Do when XYZ not defined */ #endif /* !defined(XYZ) */ /* Wrong */ #if defined(XYZ) #if defined(ABC) /* do when ABC defined */ #endif /* defined(ABC) */ #else /* defined(XYZ) */ /* Do when XYZ not defined */ #endif /* !defined(XYZ) */ 

/**
 * \brief           Holds pointer to first entry in linked list
 *                  Beginning of this text is 5 tabs (20 spaces) from beginning of line
 */ static type_t* list;

/**
 * \brief           This is point struct
 * \note            This structure is used to calculate all point
 *                      related stuff
 */ typedef struct { int32_t x; /*!< Point X coordinate */ int32_t y; /*!< Point Y coordinate */ int32_t size; /*!< Point size. Since comment is very big, you may go to next line */ } point_t; /**
 * \brief           Point color enumeration
 */ typedef enum {
    COLOR_RED, /*!< Red color. This comment has 12x4 spaces offset from beginning of line */ COLOR_GREEN, /*!< Green color */ COLOR_BLUE, /*!< Blue color */ } point_color_t;

/**
 * \brief           Sum `2` numbers
 * \param[in]       a: First number
 * \param[in]       b: Second number
 * \return          Sum of input values
 */ int32_t sum(int32_t a, int32_t b) { return a + b;
} /**
 * \brief           Sum `2` numbers and write it to pointer
 * \note            This function does not return value, it stores it to pointer instead
 * \param[in]       a: First number
 * \param[in]       b: Second number
 * \param[out]      result: Output variable used to save result
 */ void void_sum(int32_t a, int32_t b, int32_t* result) {
    *result = a + b;
}

/**
 * \brief           My enumeration
 */ typedef enum {
    MY_ERR, /*!< Error value */ MY_OK /*!< OK value */ } my_enum_t; /**
 * \brief           Check some value
 * \return          \ref MY_OK on success, member of \ref my_enum_t otherwise
 */ my_enum_t check_value(void) { return MY_OK;
}

/**
 * \brief           Get data from input array
 * \param[in]       in: Input data
 * \return          Pointer to output data on success, `NULL` otherwise
 */ const void * get_data(const void* in) { return in;
}

/**
 * \brief           Get minimal value between `x` and `y`
 * \param[in]       x: First value
 * \param[in]       y: Second value
 * \return          Minimal value between `x` and `y`
 * \hideinitializer
 */ #define MIN(x, y)       ((x) < (y) ? (x) : (y)) 

/**
 * \file            template.h
 * \brief           Template include file
 */ /* Here is empty line */ 

/**
 * \file            template.h
 * \brief           Template include file
 */ /*
 * Copyright (c) year FirstName LASTNAME
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge,
 * publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
 * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * This file is part of library_name.
 *
 * Author:          FirstName LASTNAME 
 */ 

/* file.h ... */ #ifndef ... extern int32_t my_variable; /* This is global variable declaration in header */ #endif /* file.c ... */ int32_t my_variable; /* Actually defined in source */ 

/* License comes here */ #ifndef TEMPLATE_HDR_H #define TEMPLATE_HDR_H /* Include headers */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /* File content here */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* TEMPLATE_HDR_H */