Overview

Why a Style Guide?

A solo programmer, working alone, has little need to adopt anything resembling consistent coding conventions. When no one else will ever see your code, you are the only person to benefit from any consistencies in it, or have your progress hampered by any inconsistencies. Some large multi-programmer shops sidestep the issue by partitioning the developers into silos, assigning each of them exclusive ownership of some subset of the master source for a project; as long as interfaces are clearly established between subsystems, it doesn't matter a whit to them if the developers follow the same, or even similar conventions.

However, in the world that Art & Logic inhabits, our consistent coding style is a strategic strength; the ease with which our developers can easily slip from language to language, project to project, and platform to platform gives us the ability to remain agile and highly responsive to the changing needs of our clients.

This document is an extension of the original programming style guide developed by A&L's founders before beginning work on their first project together for A&L in 1991. As the company has grown, the benefits of maintaining consistent style across projects has proven its value on an ongoing basis. It is also an encouraging sign that as the programming landscape has shifted since the company's founding, that original style has only required extension and fine tuning, not any serious rework.

What Does This Style Guide Not Cover?

In an ideal world, this document would tell you everything you need to know about the conventions used to write code while working at A&L. However, this world is not an ideal one.

When a client specifically requests that we adopt their coding conventions when working on their project, we will do so happily. In fact, the opposite case happens far more frequently, and more than a few current and former clients have adopted the A&L style (or a style derived from ours).

There may also be other reasons to deviate from this style guide. Consistency of programming style is important, but we must not encourage a foolish consistency. When deviations are appropriate, seek first to maintain consistency within each individual line of source, then within each function, each source file, and each project. In other words, keep deviations from A&L style as localized as possible.

Also, this document must be restricted to speaking in fairly broad strokes, as its main goal is to illustrate the conventions to follow in the most common cases. Any project of significant size will probably need to establish additional, local conventions to extend (but not replace) the practices outlined here. As an example, a large project that uses a complex class hierarchy should develop and consistently use a logical naming convention for the project. Once developed, any project-specific conventions should be documented in the project's ReadMe.txt file.

Changes Since Earlier Versions

The most noticeable change in this release of the Art & Logic Programming Style Guide is that it is intentionally polyglot. The first version of this guide was explicitly a C++ style guide. The second major release (April 2000) was intended as a general style guide, but its emphasis on C++ (and failure to mention any other languages) led to confusion in some quarters, even to pockets of belief that the A&L style guide had absolutely no bearing on any language except C++. This release of the style guide is meant to correct those misunderstandings.

Languages that should be coded according to the principles outlined in this guide include the main programming languages that we use:

  • C++
  • Python
  • Javascript
  • Objective-C
  • Actionscript
  • C
  • C#
  • Java
  • PHP

The examples in this document are intended to be as inclusive as possible; we count on the common sense of each developer to ignore sections of this document covering features not found in their current language (for example, any discussions of preprocessor macros or C++ template formatting will have no impact on Java programmers). Similarly, we count on the common sense of each developer to intelligently extrapolate the examples shown here to other languages that have features or constructs similar to those shown in the examples (for example, the rules for formatting of #include statements in C or C++ should be applied directly to the ordering of import statements in Python or Java.)

We also count on the common sense of our developers to approach any work done in languages other than those on the above list by working to maintain the spirit of Art & Logic style, extending our style by applying the principles laid out here.

Rosetta code

To reduce the effort (and ambiguity!) involved when applying the principles in the A&L Style Guide to each of the major languages that we work with, we have developed a series of Rosetta Stone examples that start from the same chunk of functionality and express it in each of those languages using A&L Style. You can find these in a separate section at the end of the guide. Note that these function as a reference, not a substitute for reading the style guide and understanding its principles.

The other significant change from earlier versions of this guide is organizational.

Organizing Principles

This document is organized starting at an 'orbital view' of Art & Logic projects, and continues to drill down to finer and finer levels of detail as it progresses.

Language Dependence and Language Independence

One aspect of Art & Logic's programming style that may catch some people off guard when first encountering it is our desire to make A&L code look like A&L code, regardless of the language being programmed. While this may seem odd when viewed from the position of a programmer working only in a language where different stylistic conventions are commonly used, it greatly eases the process of moving from project to project, and language to language here at Art & Logic.

While this Style Guide attempts to discuss programming style in as universal a way as possible, we also admit that each language we use will require some amount of specialization to adapt to the unique features, abilities, or oddities of each programming language used at Art & Logic. As a rule, we don't work with languages that stray too far from the ALGOL tree, so this approach works without too much difficulty. If we did a large amount of work in LISP, Forth, Smalltalk, or other languages that originate in different schools of thought, we might need to approach this issue differently.

Code Snippets

This document contains numerous code snippets to illustrate the points being made; several of the languages used at A&L are used for these examples. Many of them are not complete pieces of code, and we count on the reader to supply the missing context that would permit these snippets to make sense.

In this document, code examples are

   formatted like this.

Rule Identifiers

Each of the style rules or guidelines in this document have been assigned identifiers to make it easier to refer to them. These are marked up in the style guide like [sn##], where sn is a short mnemonic for the section of the guide (e.g., rules on Naming Rules use the mnemonic nr), and ## is a two digit number. Once assigned a number in this document, the rule ID should never change. This means that as the style guide is maintained, the sequence of numbers found on a page may change as the document is re-ordered, or as rules are added or deleted.

Each of the rule identifiers may be referenced using the HTML fragment URL syntax; for example, you can link directly to the rule about using abbreviations in source code with the URL http://styleguide.artandlogic.com/naming-rules#nr15