A coding standard is a set of guidelines and best practices that help ensure code consistency, readability, and maintainability across a development team or organization. It defines the conventions for writing code, including aspects such as naming conventions, indentation, comments, file structure, and error handling. By adhering to a coding standard, developers can collaborate more effectively, reduce the likelihood of introducing bugs, and improve the overall quality of the software. Coding standards also facilitate onboarding new team members and make it easier to review, maintain, and scale projects over time.
The file starts with a detailed comment header, specifying copyright information, licensing details, and legal
disclaimers.
The header includes details about the ownership, permissions, and terms of use.
Source files contain the body of the code for a given module, and can be broken down into parts, which must appear in the following sequence:
Necessary standard libraries are included at the top of the file (e.g, inttypes.h, stdio.h, unistd.h), ensuring that dependencies are explicitly declared. Local module-specific headers are also included.
Several #define pre-processor directives are used to define constants and strings .Each macro is preceded by a brief comment explaining its purpose.
Functionality, constants, and macros are documented using comment blocks, ensuring clarity about their usage.
All macro names are written in uppercase and follow a consistent naming convention, typically starting with the ATSCCORE_ prefix to indicate they are part of the ATSC core.
Header files are used exclusively for declarations, ensuring that the implementation (definitions) resides in the corresponding source files.
When including files in a source file, it is essential to maintain a logical and consistent ordering to enhance readability and avoid potential conflicts. The inclusion of files should follow these guidelines:
Before the function definition, there should be a comprehensive comment header that explains the purpose of the function, parameters, and return value. It should also include any preconditions, assumptions, or notable behaviors.
The function definition matches the pre-defined prototype, with clearly named parameters in the parenthesis. If the function had no parameters, the void keyword would be explicitly declared.
If any static variables were required, they would be defined here at the top of the function and initialized as necessary. Static variables would emphasize the impact on memory usage.
Error conditions should handled properly, with error flags or early exits. The function avoids the use of multiple return points, adhering to the standard of having a single exit point.
The function concludes with a single return statement, adhering to the standard of avoiding multiple exit points. The return value is 0, signaling successful execution. Any error flags or conditions(eATSCResult_t) would have been handled earlier in the function without disrupting the flow.
Variables are prefixed to indicate their type or purpose:
i: For integer values (e.g., iMessageId ). This is a common convention that makes it immediately clear that the variable stores an integer.
p: For pointers (e.g., pData). This prefix makes it evident that the variable holds an address to a data buffer.
s: For string or character arrays (e.g., sMsgData), making it easier to distinguish arrays from other variable types.
ll: For long long or 64-bit integer types (e.g., llDstLen), denoting larger integers or specific memory sizes.
c : For character variable
b : For boolean flags
f : For Float variables.
d : for Double variable.
m : Class member variables.
Variables are given descriptive names that convey their purpose and role within the function, improving readability:
Ex: iMessageId: This stores the message identifier, clearly indicating its purpose.
Variables are grouped based on related functionality.
Ex:Timestamp-related variables use a common prefix (iTimestampSec, iTimestampFrac, etc.), creating
consistency in the code.
Variables with multi-word names follow the camelCase convention, where each word starts with a capital letter,
making them easy to read:
Ex: iAtsc3MessageContentVersion
A comment header is provided at the top of the structure, briefly explaining the purpose of the structure. According to coding standards, the comment should provide a more detailed description of the structure’s role, its members, and how it is used.
Each member of the structure has a corresponding comment that explains its purpose. The comments use the /**< Example > format and provide a clear, concise description.
The structure uses consistent data types such as int32_t and uint32_t, adhering to the standard practice of using
fixed-width integer types to ensure portability across platforms.
The use of int32_t and uint32_t also ensures that developers are aware of the size and range of the variables,
which is especially useful when dealing with cross-platform compatibility.
Grouping related variables improves readability and helps maintain a logical flow within the structure.
The structure uses a typedef to define a convenient alias, which simplifies the use of the structure in the rest of the code.
Ex : The enum name eATSCResult_t follows a consistent and descriptive naming convention: