Mastering Clean C: Essential Coding Standards for Reliable Software

Scope

This specification applies to C language products and takes effect from the date of publication; all newly written or modified code must comply.

Introduction

The specification establishes basic principles, rules, and recommendations for writing C language products, providing concrete guidance on clarity, conciseness, testability, safety, efficiency, and portability.

Preface

To improve product code quality and help developers produce concise, maintainable, reliable, testable, efficient, and portable code, this standard draws on industry programming guidelines and tailors them for C language products.

Overall Philosophy

Clarity First

Clear code is essential for maintenance and refactoring; code is read by people first. High readability reduces maintenance costs, which can dominate 40%‑90% of a system’s lifecycle. As quoted by Harold Abelson and Gerald Jay Sussman, "Programs must be written for the people who read them, not just for machines." The standard emphasizes self‑explanatory code, appropriate header declarations, and avoidance of obscure abbreviations.

Simplicity is Beauty

Simplicity means easy understanding and implementation. Longer code is harder to read and more error‑prone. Redundant or dead code should be removed, and repeated code should be refactored into functions.

Consistent Style

Teams should share a common style. When refactoring code with a different style, follow the existing style or use automated tools to convert.

Terminology

Principle : Guiding ideas that must be followed. Rule : Mandatory conventions. Suggestion : Considerations to take into account. Explanation : Clarifications for principles/rules/suggestions. Example : Positive and negative examples.

Basic Principles

Principle : Program structure should be clear; a single function should not exceed 200 lines.

Principle : Keep intent simple and direct; avoid junk code.

Principle : Prefer standard library and common functions.

Principle : Minimize global variables; use locals when possible.

Suggestion : Use parentheses to avoid ambiguity.

Operator Parentheses

Examples:

x = ~a;

x = -a;

For binary or higher operators involving different precedence, use parentheses: x = (a == b) ? a : (a - b); When mixing types or promotions, parentheses clarify evaluation order.

Readability Requirements

Rule : Keep comments consistent with code.

Rule : Document major variables and structures.

Rule : Provide explanations for constants.

Rule : Comment key stages of critical processes.

Principle : Use uniform indentation (tabs only).

Rule : Limit nesting depth; avoid overly deep loops and branches.

Rule : Re‑entrant functions must avoid shared variables or protect them with mutexes.

Correctness and Fault Tolerance

Suggestion : Prioritize correctness before elegance.

Suggestion : Review code for hidden errors after changes.

Rule : Validate all user input at the outermost layer.

Rule : Never compare floating‑point numbers for equality.

Rule : Enclose macro expressions in complete parentheses.

Rule : Prevent memory leaks and dangling pointers.

Performance and Optimization

Principle : Improve efficiency while preserving correctness, simplicity, maintainability, reliability, and testability.

Principle : Optimize data structures and algorithms.

Suggestion : Move invariant calculations out of loops.

Suggestion : Avoid strided access of multi‑dimensional arrays; access elements in memory order.

Suggestion : Use resource pools to reduce allocation overhead.

Suggestion : Inline small frequently called functions or use macros.

Compilation

Principle : Enable appropriate compiler warnings and fix them rather than suppressing.

Rule : Keep local build tool configurations consistent with CI.

Rule : Use version control and commit code that builds successfully.

Testability

Principle : Clear module boundaries, explicit interfaces, low coupling, and well‑defined inputs/outputs enable unit testing.

Suggestion : Focus tests on unit behavior rather than implementation details.