Essential C Coding Style Guide: Naming, Headers, and Comments

Preface

When developing pure C code, especially within an SDK, every line should match the existing style to avoid breaking the overall codebase. Good coding standards reflect a developer’s attention to detail and code quality.

Core Principles

Clarity is key – Code must be readable not only by the compiler but also by humans. Write code as if it were an article: clear and easy to understand.

Simplicity is beauty – Shorter code is easier to understand and modify, reducing bugs. Remove dead code, eliminate unnecessary parts, and refactor duplicated logic into functions.

Consistent style – Using a unified coding style smooths team collaboration. Follow the project’s existing style guide or adopt a standard one, and use tools to enforce it.

Naming Conventions

General Rules

Names should be descriptive, avoid excessive abbreviations, and use nouns for types and variables, while functions use imperative verbs.

int num_errors;          // Good
int num_completed_connections; // Good

Bad examples:

int n;          // Bad – meaningless
int nerr;       // Bad – ambiguous abbreviation
int n_comp_conns; // Bad – ambiguous abbreviation

Variable Naming

Use lowercase with underscores; class member variables end with an underscore.

my_exciting_local_variable
my_exciting_member_variable_

Constant Naming

Prefix constants with k and use PascalCase.

const int kDaysInAWeek = 7;

Enum Naming

Enum values are all caps with underscores; enum types use mixed case.

enum UrlTableErrors {
  OK = 0,
  ERROR_OUT_OF_MEMORY,
  ERROR_MALFORMED_INPUT,
};

Macro Naming

Avoid macros; if necessary, name them like enums (all caps with underscores).

#define ROUND(x) ...
#define PI_ROUNDED 3.0

File Naming

File names should be lowercase, may contain underscores or hyphens, and be descriptive.

my_useful_class.cc
my-useful-class.cc
myusefulclass.cc

Avoid colliding with system headers (e.g., db.h) and prefer explicit names like http_server_logs.h over generic logs.h.

Header Files

Every .cc file should have a matching .h file, except for test files or files containing main(). Use include guards to prevent multiple inclusion, following the pattern <PROJECT>_<PATH>_<FILE>_H_.

#ifndef FOO_BAR_BAZ_H_
#define FOO_BAR_BAZ_H_
...
#endif // FOO_BAR_BAZ_H_

Minimize header dependencies by using forward declarations whenever possible, reducing the number of #include statements and thus compilation overhead.

class File; // Forward declaration instead of #include "file/base/file.h"

Include Order

Standardize include order for readability and to avoid hidden dependencies: C library headers, C++ library headers, third‑party .h files, then project headers.

#include "base/logging.h"

Comments

Comments are essential for code readability but should not duplicate obvious information. Use // or /* */ consistently.

Class comments should describe the class’s purpose and usage.

Function comments at the declaration should list inputs, outputs, ownership semantics, nullability, performance considerations, and re‑entrancy requirements.

inputs and outputs

parameter ownership

memory allocation responsibilities

NULL acceptance

performance pitfalls

re‑entrancy constraints

Avoid redundant comments such as “returns false otherwise” when the return type already implies it.

Code Style

Adopt a uniform style across the project. Limit line length to 80 characters for consistency, even if controversial.

Overall, a coding style guide provides a shared standard so developers can focus on implementation rather than formatting.