Coding Guidelines

From Adobe Open Source Wiki
Revision as of 00:48, 17 September 2006 by SeanParent (Talk | contribs)

Jump to: navigation, search

This section is for collecting our coding standards and style. This is primarily of importance to contributors.

Contents

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-2006 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>

Include Guards

Line Endings

Line Lengths

Comments

Spaces vs. Tabs

Naming