Coding Guidelines - Revision history

FosterBrereton at 16:29, 4 April 2007

2007-04-04T16:29:20Z

FosterBrereton at 16:28, 4 April 2007

2007-04-04T16:28:41Z

FosterBrereton at 16:27, 4 April 2007

2007-04-04T16:27:48Z

FosterBrereton at 16:23, 4 April 2007

2007-04-04T16:23:29Z

SeanParent: /* Line Endings */

2006-09-22T05:26:06Z

‎Line Endings

SeanParent: /* Include Guards */

2006-09-22T05:25:08Z

‎Include Guards

SeanParent: /* File Naming and Structure */

2006-09-22T05:20:24Z

‎File Naming and Structure

SeanParent: /* File Naming and Structure */

2006-09-22T05:09:09Z

‎File Naming and Structure

SeanParent: /* Introduction */

2006-09-17T00:48:05Z

‎Introduction

SeanParent: Starting our style guide

2006-09-16T04:03:09Z

Starting our style guide

New page

''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 [http://safari.awprofessional.com/0321113586/pref01 ''C++ Coding Standards: 101 Rules, Guidelines, and Best Practices''] by Herb Sutter, Andrei Alexandrescu.

I would also recommend the online paper [http://f1.grp.yahoofs.com/v1/sGgLRd2UDdCa_xkWG4jo9TDHCTsvop18BTxBagwdw17E1Eut_oYTOV0L2s5xkOHpXq3eTmVoXpBTHAV2nDZ9D-LBSf8gQDd7TQ/coding_guidelines.html ''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 [http://www.stepanovpapers.com/notes.pdf 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.

@@ Line 62: / Line 62: @@
 === Line Endings ===
-All files in ASL should use a Unix line endings, a single lf character.
+All files in ASL should use a Unix line endings, a single LF character.
 === Line Lengths ===
@@ Line 74: / Line 74: @@
 === 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.
+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.

@@ Line 66: / Line 66: @@
 === Line Lengths ===
-In general, no line of code should exceed 80 characters.
+In general, no line of code should exceed 80 characters (including any indentation).
 === Comments ===
-Comment in abundance, but not for the sake of commenting.
+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.

@@ Line 65: / Line 65: @@
 === Line Lengths ===
 === Comments ===
 === Spaces vs. Tabs ===
-== Naming ==

@@ Line 20: / Line 20: @@
 <pre>
 /*
-     Copyright 2005-2006 Adobe Systems Incorporated
+     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)

@@ Line 61: / Line 61: @@
 === Line Endings ===
 === Line Lengths ===
 === Comments ===
 === Spaces vs. Tabs ===
 == Naming ==

@@ Line 38: / Line 38: @@
 Where possible - organize the files to match the organization used in STL and Boost. For example, algorithms can be found in <code>adobe/algorithm.hpp</code>. 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 - <code>adobe/algorithm.hpp</code> will include <code>adobe/algorithm/reverse.hpp</code>.
-To further reduce the amount of code included, where possible include a header which only contains forward, or minimal declaration.
+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 <code>_fwd</code> and only include by other header files. For example <code>adobe/name_fwd.hpp</code>.
 === Include Guards ===

@@ Line 35: / Line 35: @@
 #include <adobe/algorithm/reverse.hpp>
 </pre>
 === Include Guards ===

← Older revision		Revision as of 00:48, 17 September 2006
Line 12:		Line 12:

	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.		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:
		+
		+	<pre>
		+	/*
		+	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)
		+	*/
		+	</pre>
		+
		+	=== File Naming and Structure ===
		+
		+	Source file names are all <code>lower_case</code>. C++ headers have a <code>.hpp</code> suffix. C++ source files have a <code>.cpp</code> suffix. The include files for ASL are all within the <code>adobe</code> directory and are included using the system include quotes, <code><...></code>.
		+
		+	Example:
		+
		+	<pre>
		+	#include <adobe/algorithm/reverse.hpp>
		+	</pre>
		+
		+	=== Include Guards ===
		+	=== Line Endings ===
		+	=== Line Lengths ===
		+	=== Comments ===
		+	=== Spaces vs. Tabs ===
		+	== Naming ==