Skip to content

Latest commit

 

History

History
117 lines (83 loc) · 3.39 KB

style_guide.md

File metadata and controls

117 lines (83 loc) · 3.39 KB

SML-lib C/C++ Style Guide

File Organization

  • Use a clear, concise, and consistent naming convention for your source code files.
  • Use appropriate header guards to prevent multiple inclusions of header files.
  • Separate headers and implementation files.
// Good example
#ifndef MY_HEADER_H
#define MY_HEADER_H

// Header content

#endif // MY_HEADER_H

Code Formatting

  • Use the provided .clang-format settings for code formatting.
  • Use a consistent indentation style. The provided settings specify an indentation of 4 spaces.
  • Keep code lines within a reasonable character limit (usually around 80-120 characters per line).

Comments

  • Use comments to explain non-trivial sections of code, particularly if they are not self-explanatory.
  • Add comments to clarify the purpose of functions, variables, and complex logic.
  • Include comments at the top of each source file to describe its purpose and any relevant information.
// This is an example of a file-level comment describing the contents and purpose of the file.

Code Structure

  • Use a clear and consistent code structure. In the provided code, use consistent spacing and formatting.
  • Group related functions and variables together.
  • Use meaningful function and variable names. Ensure that their naming adheres to a consistent convention.

Error Handling

  • Use appropriate error handling mechanisms, like returning error codes or exceptions.
  • Provide clear and descriptive error messages when reporting errors.
// Good example
if (error_condition) {
    return ERROR_GENERIC;
}

// Provide a descriptive error message when needed
sml_throw_error(cfg, ERROR_GENERIC, LOG_SEVERITY_ERROR, "An error occurred: %s", error_message);

Function and Variable Naming

  • Use descriptive function and variable names to make the code self-documenting.
  • Follow a consistent naming convention (e.g., camelCase or snake_case) for functions and variables.
// Good example
int calculateTotalPrice(int itemPrice, int quantity);

Macros

  • Use macros with uppercase letters and underscores to represent constants.
  • Provide comments explaining the purpose and usage of macros.
// Good example
#define MAX_SML_NAME_LEN 256

Testing

  • Include test functions to verify the correctness of your code.
  • Organize test functions in a separate section or file.
  • Document how to run tests and include example test cases.
// Example test function
void test_error_lib(void) {
    // Test cases and assertions
}

Debug Mode

  • Enable and disable debug mode through preprocessor directives, as shown in the provided code.
  • Use debug mode for debugging and development purposes, and ensure it doesn't affect the production code.
#if (DEBUG == 1)
    // Debug-related code
#else
    // Production code
#endif

Version Control

  • Use version control tools like Git to manage your codebase.
  • Follow a clear and consistent commit message format to provide information about changes.
feat: Add new feature XYZ
fix: Fix issue with ABC
docs: Update documentation

Other Considerations

this is not strictly governed, but it helps code readability. Hope you have fun!

By following these guidelines, you can maintain a clean, consistent, and readable codebase for your project. Make sure all contributors are aware of and follow this style guide to ensure code quality and maintainability.