C++Standard/Introduction

Draft for new release V 1.6

This document is being updated to reflect changes approved by the DM TCT. The document is in transition.

The previous official version of the C++ Programming Style Guidelines (V 1.5) is available here.

Rule changes in V1.6 are available here.

LSST Data Management: C++ Programming Style Guidelines


Table of Contents

  1. Draft for new release V 1.6
  2. 1 Introduction
    1. 1.1 Layout of the Recommendations
    2. 1.2 Recommendation Importance
      1. REQUIRED
      2. MUST or SHALL
      3. SHOULD or RECOMMENDED or MAY

1 Introduction

This document lists C++ coding recommendations common in the C++ development community. The recommendations are based on established standards collected from a number of sources, individual experience, local requirements/needs, as well as suggestions given in References (1 - 4). There are several reasons for introducing a new guideline rather than just referring to the ones above. Main reason is that these guides are far too general in their scope and that more specific rules (especially naming rules) need to be established. Also, the present guide has an annotated form that makes it far easier to use during project code reviews than most other existing guidelines. In addition, programming recommendations generally tend to mix style issues with language technical issues in a somewhat confusing manner. The present document does not contain any C++ technical recommendations at all, but focuses mainly on programming style.

While a given development environment (IDE) can improve the readability of code by access visibility, color coding, automatic formatting and so on, the programmer should never rely on such features. Source code should always be considered larger than the IDE it is developed within and should be written in a way that maximizes its readability independent of any IDE.

1.1 Layout of the Recommendations

The recommendations are grouped by topic and each recommendation is numbered to make it easier to refer to during reviews.

Layout of the recommendations is as follows:

x.y Guideline

Short description 

  Example if applicable

Motivation, background and additional information.

The motivation section is important. Coding standards and guidelines tend to start "religious wars", and it is important to state the background for the recommendation.

1.2 Recommendation Importance

In the guideline sections, the terms 'must', 'should' and 'may', amongst others, have special meaning. We will use the spirit of the IETF organization's RFC 2199 Reference(10) definitions; they are paraphrased below for our purpose:

REQUIRED

  • REQUIRED means that the Rule is an absolute requirement of the specification. The developer needs to petition the DM TCT to acquire explicit approval to contravene the Rule.
  • PROHIBITED is the opposite of REQUIRED.

MUST or SHALL

  • MUST and SHALL mean that there may exist valid reasons in particular circumstances to ignore a particular Rule, but the full implications must be understood and carefully weighed before choosing a different course. The developer needs to petition the lead developer to acquire explicit approval to contravene the Rule.
  • MUST NOT and SHALL NOT are their opposites.

SHOULD or RECOMMENDED or MAY

  • SHOULD, RECOMMENDED and MAY mean that there are valid reasons in particular circumstances to ignore a particular Rule. The developer is expected to personally consider the full implications before choosing a different course.
  • SHOULD NOT, NOT RECOMMENDED and MAY NOT are their opposites.