Dataphor.org

Dataphor Coding Standards & Conventions

Modified: 2009/04/08 00:29 by n8allan - Categorized as: Development
Despite its size, the Dataphor codebase is relatively clean and consistent, largely due to an attempt to strictly follow some well-argued coding standards that have evolved over years of practical usage. These standards are by no means perfect, nor are they set in stone, but a change must be defensible and agreed upon before the standards can be changed. In order to avoid creating busywork, changes to the standards apply to new code. Old code should be updated as encountered when performing maintenance, but code changes for the sake of applying new standards are generally avoided.

Note that code contributions that do not strive towards these standards will be returned for further cleanup.

The ultimate goal of these coding standards is to improve readability (and therefore maintainability) by eliminating personal nuance in favor of consistency. The basic idea is that it should not be possible to tell which developer is responsible for a particular peice of code.

Each section below describes a particular group of standards, together with the reasoning behind the standards, and some practical examples of their usage.

Edit

Naming Conventions

Edit

Pascal-casing for all identifiers (no camel-casing, ever)

Because C# is a case-sensitive language, and all reserved words in the language are lowercase, the use of Pascal-casing ensures a complete namespace in all cases. The choice of identifier is never a compromise due to a naming conflict with a keyword in the language. Edit

Prefix delineation

When reading code, it is useful to be able to determine the source of a particular identifier at a glance. This prefix notation, together with standard C# syntax highlighting, provides a complete mechanism for this identification. The following language elements require prefix delineation:
  • Arguments (A)
  • Local Variables (L)
  • Fields (F)
  • Constants (C)
Edit

Acronyms must be fully capitalized

We follow the standard English convention of capitalizing all the letters of an acronym when it appears in an identifier. Edit

Avoid meaningless identifiers

Identifier names should be chosen carefully to attach as much meaning as possible. Nomenclature and meaning are inextricably linked, and a well chosen identifier can literally be the difference between an elegant solution, and an unmaintainable mess. Edit

Avoid abbreviations

Abbreviations are often counter-intuitive and vary from person to person. If abbreviations are used at all, they must be agreed upon prior to being used. Edit

No underscores

The use of underscores adds another variable to the identifier pot, needlessly complicating the selection and decoding of a name.

Edit

Statements, Expressions, and Blocks

Edit

Statements

Each statement should begin on a new line. Edit

Indentation

Indentation should be used to show dependence on the previous statement. Identation should always be accomplished with tabs, one tab per indentation level. Editors should be set to keep tabs, not spaces. Edit

Blocks

Beginning block delimiters should be placed on the next line at the same indentation level as the opening statement, with all the statements inside the block indented one level further. The ending block delimiter should align with the beginning block delimiter. Edit

Multi-line Statements

If a statement is longer than a single line will allow, it should be split onto multiple lines. The split can occur along several boundaries including parentheses, braces, indexers, array selectors, object initializers, and built-in operator invocations. Edit

No right-aligned constructs

Right-aligning statements (such as attempting to place the arguments of a call vertically aligned with the first argument in the call) cause needless code maintenance. Edit

Whitespace

Whitespace must be used consistently and sparingly. Proper use of whitespace to help delineate steps within a method can greatly improve readability. It follows that improper use of whitespace can hinder and even destroy readability. We therefore attach great significance to the consistent and correct usage of whitespace within code.
  • Spaces after commas to separate items in a list
  • Spaces after all reserved words
  • No spaces before or after parentheses
  • Spaces before and after braces
  • Use tabs for indentation, not spaces
  • Single tab per indentation level
  • Never use more than a single hard return to separate code
Edit

Collapsing

In general, blocks should always span multiple lines and new statements should always begin a new line. However, to improve readability, there are certain allowed exceptions to this rule:
  • Property accessors may be collapsed if the entire definition will fit on a single line.
  • Common if statements such as logging statements may be collapsed to avoid the code bloat that would otherwise occur.

Edit

Comments

Edit

General Guidelines

  • Comments should be terse and useful.
  • No comments are better than bad comments.
  • Good comments are better than no comments.
Edit

Avoid Commented-Out Code

While there are reasons to leave commented-out code in the code base, they are few and far between. Consider introducing a compiler define rather than a comment. At the very least, comment the exclusion.

Edit

Annotations

Not all comments are required to be annotations, but annotations should be used to reflect areas of the code that should be revisited or otherwise require special attention.

Annotations should include a comment type, the date of the comment, and the initials of the commenter. Available comment types include:
  • // TODO:
  • // HACK:
  • // NOTE:
  • // WORKAROUND:

ScrewTurn Wiki version 2.0.36. Some of the icons created by FamFamFam.