Coding Guidelines
Contents
This section is for collecting our coding standards and style. This is primarily of importance to contributors.
Introduction
We could write an entire book on coding guidelines but luckily that has already been done. I’d recommend reading C++ Coding Standards: 101 Rules, Guidelines, and Best Practices by Herb Sutter, Andrei Alexandrescu.
I would also recommend the online paper C++ Coding Guidelines by David Abrahams and Nathan Myers. This document follows a similar format and I will only attempt to document where our guidelines differ or are more refined.
To understand the importance that naming plays in generic programming, I’d recommend working through Notes on Programming by Alex Stepanov. In fact, before writing any code I’d recommend working through this document.
The style of ASL is a refinement of the style used in the standard library as well as in the Boost libraries. A good general rule is to defer to the highest authority.
ASL is, primarily, a research project even though we strive to make each piece of commercial quality (after all, it is research into how to write large scale systems correctly!). In order to be able to push ASL forward, it is important that each piece is written as correctly as we can. To that end, if there are improvements we can make to the style and interfaces we will, even if that breaks backward compatibility. The challenge of versioning the interfaces in a library such as ASL is an area of research I hope to tackle at some point but for now the burden of maintaining backward compatibility is too high.
Files and the Preprocessor
License
Every file must include the following license as the first item in the file:
/*
Copyright 2005-2007 Adobe Systems Incorporated
Distributed under the MIT License (see accompanying file LICENSE_1_0_0.txt
or a copy at http://opensource.adobe.com/licenses.html)
*/
File Naming and Structure
Source file names are all lower_case. C++ headers have a .hpp suffix. C++ source files have a .cpp suffix. The include files for ASL are all within the adobe directory and are included using the system include quotes, <...>.
Example:
#include <adobe/algorithm/reverse.hpp>
Where possible - organize the files to match the organization used in STL and Boost. For example, algorithms can be found in adobe/algorithm.hpp. Break up files to a fine granularity to reduce the amount of information which must be included to be compiled. Organize the small headers in a directory with the same root as the master header - adobe/algorithm.hpp will include adobe/algorithm/reverse.hpp.
To further reduce the amount of code included, where possible include a header which only contains forward, or minimal declaration. Such header files should be suffixed with _fwd and only include by other header files. For example adobe/name_fwd.hpp.
Include Guards
All header files should have internal include guards after the license. The include guards are named the same as the file, including the file path, with punctuation replaced by the underscore character.
Example:
#ifndef ADOBE_ALGORITHM_REVERSE_HPP #define ADOBE_ALGORITHM_REVERSE_HPP //... #endif
Although some compilers will let you get away with it, comments are not allowed in preprocessor directives.
Incorrect:
#endif // ADOBE_ALGORITHM_REVERSE_HPP
Line Endings
All files in ASL should use a Unix line endings, a single LF character.
Line Lengths
In general, no line of code should exceed 80 characters (including any indentation).
Comments
Comment, but for the sake of the developer who will maintain your code, not for the sake of commenting.
Spaces vs. Tabs
Due to horrific global conflict over the accepted tab-to-space conversion ratio, tabs are to be avoided at all cost within the sources. Indenting, however, is highly recommended where appropriate, and should be 4 spaces wide.