-
Notifications
You must be signed in to change notification settings - Fork 223
Coding Standards
Coding standards take two general forms:
- coding guidelines
- style guidelines
This wiki page discusses the general role of each and provides links to the details of the guidelines for each
Style guidelines are focused on the appearance of the source code itself. That is, Style guidelines are focused on using the visual aspects of code layout, commenting, formatting and naming conventions to convey information about the intended behavior of the code to a human reader.
As there are many ways to structure and organize code that ultimately generates the same binary executable a large amount of passionate debate can occur around this area. Thus, teams often get bogged down with this trying to achieve team consensus on what are in many cases purely arbitrary choices between two equally viable options. While the guidelines here use the terms "BAD" and "GOOD" or "CORRECT and "INCORRECT" these terms are relative only to the guidelines listed here and not intended as a reflection of the merits of anyone's favorite style.
The .NET Micro Framework is an Open Source project with a number of users and, if we do our job well, a growing developer community. Thus, style becomes more important to help ensure that reviewers can focus on reviewing the correctness of the code instead of wrapping their heads around yet another style. While all new code should aspire to comply with the guidelines completely there is a good chance that at some point the guidelines are non-specific or would actually make the code harder to understand. In these cases the ultimate rule of rules for style guidelines comes in to play:
Style guidelines are designed to allow a developer to use patterns of visual clues to help convey the intent, structure and flow of the code and or data.
While arbitrary violation of style guides leads to confusing, and harder to read and maintain code, dogmatic adherence without grasping the primary rule of style guidelines can be even worse. Thus, violations of the guidelines should raise a flag for reviewers. Submitters must provide reasonable justification for the exception and reviewers should consider the ultimate goal of style rules when considering if the exception is warranted.
A general thought experiment applied to style guidelines can help in deciding appropriateness of a particular choice:
If I blurred out all the keywords and identifiers in the code could the remaining visual structure of the code convey any meaningful information about the code to the viewer?
Style is about getting to the strongest possible positive answer to that question.
Coding guidelines are focused on correctness and robustness of the source code, along with compliance to architectural patterns defined for a project. That, is they are focused mostly on the aspects of the code that affect the final run-time behavior of the system. These include language specific patterns for ensuring correct code as well as general practices for building robust systems that can recover from non-catastrophic error conditions and quickly and cleanly report unrecoverable critical failures. Coding guidelines are generally language specific with additional extensions specific to a particular runtime framework or library.
- Don't re-write existing code for the sake of meeting a guideline
Re-writing existing, working and technically correct code that doesn't happen to conform to the guidelines is generally a waste of time. One exception to this is an area of code that, based on future roadmap and design plans is expected to undergo a number of significant changes. In such a case it is often a good idea to make a single initial change that brings the source into full conformance in one shot, rather than piecemeal across multiple functional code changes. - Say it in code
Use aspects of the language to express intent and usage, don't rely on a comment or naming convention. (e.g. if a C/C++ function takes a pointer as a parameter that it only reads from - then use the 'const' keyword to express that intent and allow the compiler to enforce it) There are a number of coding rules that fall under this general rule, keeping this in mind as an overarching philosophy will help in understanding what the correct thing to do is and why.
- Do not use "Hungarian Notation"
This was a popular style for many developers, especially from Microsoft. However, over time it has proven to have issues of accuracy after refactoring. Furthermore, beyond fairly simple primitive types, Hungarian notation can result in difficult to understand names with complex prefixes requiring a "cheat sheet" to understand the type encoding in the name, which ultimately defeats the purpose of style and coding guides. - Use variable casing consistently
Many style guides forget or ignore the fact that the first letter of an identifier as Uppercase or lowercase is in fact a binary data point. That is, many guidelines make what we consider a mistake in trying to place a third contextual element to the identifier. So that if an identifier is lowercase in context "X" then it means one thing but in some other context it means something else. This just adds to confusion. Thus the guidelines for NETMF require a consistency that is independent of context. The most useful non-contextual binary condition we found was that of a variable that exists on the stack or not. Parameters to a function and local variables (both of which are on the stack) use a lowercase first character. All other variables use an Uppercase character as the first character in the identifier. - Parameter lists are either all on one line or each get their own line, but are never mixed.
This helps to clarify what belongs to what in complex code, especially when viewing a difference in a side by side fashion. Furthermore, line wrapping of parameter and initializer lists should prefer wrapping before the separating punctuation (usually a comma) and align the punctuation with the opening. Example:
// BAD
void Foo( int one, int two,
int three );
// GOOD
void Foo( int one, int two, int three );
// Better
void Foo( int one,
int two,
int three );
// BEST
void Foo( int one
, int two
, int three
);
This uses the syntax of the language to form a clear and concise visual line to aid the reader in understanding the code.
- FxCop Rules
- [StyleCop Rules](StyleCop Rules)
- C/C++ Coding guidelines
- C/++ Style guidelines