Having been involved in coding standards discussions at several jobs I've usually found the process to be an arbitrary exercise in codifying personal opinion. The conversation inevitably turns to pedantic things such as where to put curly braces or how to indent. I've started to think about how to try to focus teams on higher value areas of software engineering, and how to design coding standards to focus teams in these areas. This post is the product of those thoughts, written as a coding standards document.
Coding standards
Preface
The purpose of this document is to describe some software development practices. The topics are ordered according to their relative importance to our organization. Where critical, firm rules are specified; elsewhere the standards are intentionally relaxed so you have the freedom to express your personal preference. This document is intended to be a helpful tool that improves the quality of the engineering of our organization. It is not intended to be used as a literal interpretation of how to design or build something, or to codify personal preference. The standards in this document are based on technical reasoning.Architecture
Architectural guidelines are intended to apply to all languages.
Software modules should follow these guidelines:
- APIs should be orthogonal
- The purpose of each method should be unique. Callers can build up complex behavior by calling multiple methods through helper functions but APIs should typically not provide multiple ways to accomplish the same thing.
- Public APIs must be clearly documented.
- Modules (files, classes etc) should perform a single task.
- Modules (files, classes etc) that consist of other modules should use composition instead of inheritance
Implementation
All classes should have unit tests written against them. All unit tests should be automated where possible.Whitespace
Adequate whitespace is necessary to make the code easier to read. If people mention your code is difficult to read they might be having trouble because there is insufficient whitespace. While the code should be concise, it can help to have white space between adjacent lines of code to indicate two separate logical sections, for instance.Naming convention
The naming of classes, objects, variables etc, is important to the readability of the code. Names should attempt to clearly and concisely describe the purpose of the software object. Be open to constructive criticism.Documentation
All public APIs must be documented. All private APIs should be documented as well. Depending on the intended audience you may need to adjust or expand your documentation. It is important to provide enough information that a reader can use a web search engine and your existing comments in order to research the details of your implementation. Hyperlinks in your comments can be helpful.Coding style
Coding style is one of the easiest things to define. It is easy to specify the number of spaces before a curly brace or the number of spaces or tabs to indent given lines. Programmers tend to gravitate to coding style because, like logic, it is something that can be defined. It is important to realize that most coding style is personal preference. It may be useful to pick an arbitrary coding style for your organization so the group will produce consistently formatted code. If you've chosen an arbitrary style simply for consistency, it helps to state explicitly that the convention is arbitrary in order to allow for the style convention to evolve over time. Indicating that the coding style is arbitrary also makes it clear that there are more important areas of the coding conventions.
Coding style should follow these conventions:
- Consistency within a language that specifies a convention. Eg. .NET design guidelines or the Python style guide
- Consistency within a software application
- A programmer is permitted to use a coding style within a software application provided that
- It is a generally accepted convention, eg. K&R style
- Other developers do not find the code difficult to read
- It is maintained throughout that application
- Consistency within files
- Style should be maintained in individual files. This applies to existing as well as 3rd party code. Changes to style are permitted but should be discussed and performed as an atomic change, for example one patch to reformat an entire file.
Comments
Post a Comment