EPITA C++ Coding Style Guidelines

Next: , Up: (dir)

EPITA C++ Coding Style Guidelines

This document intends to establish a common coding style for the C++ projects of the EPITA students.

Covered topics:

The specifications in this document are to be known in detail by all students.

All submitted projects must comply exactly with these rules.

WARNING: Despite the fact that this document looks pretty much like that of the C Coding Style, it is different and specifies different rules. Read it carefully.

Some sections of this document are identical to the corresponding ones of the C Coding Style. In this case, they will not be repeated and you are asked to refer to the C Coding Style guidelines.

The rules specified in this document give you much more freedom than the C Coding Style one, use this freedom wisely.

The Tiger Compiler Assignment also has a section about Coding Style, you MUST follow it for TC. If the Tiger Assignment contradicts this document, then it is authoritative for the Tiger Compiler.

If you are a beginner in C++, you are strongly suggested to entirely read The C++ FAQ light of comp.lang.c++.

--- The Detailed Node Listing ---

How to read this document

Naming conventions

Preprocessor-level specifications

Writing style

Object Oriented considerations

Global specifications

Project layout

Differences with the C Coding Style

Index and Table of Contents

Next: , Previous: Top, Up: Top

1 How to read this document

This document adopts some conventions described in the following nodes.

Next: , Up: How to read this document

1.1 Vocabulary

These guidelines use the words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL as described in RFC 2119.

Here are some reminders from RFC 2119:

This word, or the terms REQUIRED or SHALL, mean that the definition is an absolute requirement of the specification.
This phrase, or the terms PROHIBITED or SHALL NOT, mean that the definition is an absolute prohibition of the specification.
This word, or the adjective RECOMMENDED, mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighted before choosing a different course.
This phrase, or the phrase NOT RECOMMENDED, mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
This word or the adjective OPTIONAL, mean that an item is truly optional. One may choose to include the item because a particular circumstance requires it or because it causes an interesting enhancement. An implementation which does not comply to an OPTIONAL item MUST be prepared to be transformed to comply at any time.

Next: , Previous: Vocabulary, Up: How to read this document

1.2 Rationale - intention and extension

Do not mix up the intention and extension of this document.

The intention is to limit obfuscation abilities of certain students with prior C++ experience, and make uniform the coding style of all students, so that group work does not suffer from style incompatibilities.

The extension, that is, the precision of each “rule”, is there to explain how the automated coding style verification tools operate.

In brief, use your common sense and understand the intention, before complaining about the excessive limitations of the extension.

Previous: Rationale - intention and extension, Up: How to read this document

1.3 Beware of the examples

Examples in these guidelines are there for illustratory purposes only. When an example contradicts a specification, the specification is authoritative.

Be warned.

As a side-note, do not be tempted to “infer” specifications from the examples presented.

Next: , Previous: How to read this document, Up: Top

2 Naming conventions

Names in programs must comply to several rules. They are described in the following nodes :

Next: , Up: Naming conventions

2.1 General naming conventions

The recommendations provided by the C Coding Style guidelines also apply in C++: give your {files,variables,classes,namespaces,etc} relevant (English) names.

Additionally, the following rules apply:

This section is incomplete and you must follow the guidelines specified in the section Name Conventions of Tiger Assignment.

Next: , Previous: General naming conventions, Up: Naming conventions

2.2 Name capitalization

Preprocessor macro names MUST be entirely capitalized.

Previous: Name capitalization, Up: Naming conventions

2.3 Typedef suffix

When declaring types, type names MUST be suffixed with _type

     typedef typename MyTraits<T>::res value_type;
     typedef std::map<const Symbol, Entry_T> map_type;
     typedef std::list<map_type> symtab_type;

Rationale: this is a common idiom in C++ (which happens to be used by the stl)

Rationale: for not using _t: identifiers ending with _t are reserved by posix (beside others).

Next: , Previous: Naming conventions, Up: Top

3 Preprocessor-level specifications

The global layout of files, and sections of code pertaining to the C preprocessor (which happens to be used in C++), including file inclusion and inclusion protection, must comply to specifications detailed in the following sections.

Next: , Up: Preprocessor-level specifications

3.1 File layout

Next: , Previous: File layout, Up: Preprocessor-level specifications

3.2 Preprocessor directives layout

Next: , Previous: Preprocessor directives layout, Up: Preprocessor-level specifications

3.3 Macros and code sanity

Next: , Previous: Macros and code sanity, Up: Preprocessor-level specifications

3.4 Comment layout

Previous: Comment layout, Up: Preprocessor-level specifications

3.5 Header files and header inclusion

Next: , Previous: Preprocessor-level specifications, Up: Top

4 Writing style

The following sections specify various aspects of what constitutes good programming behavior at the lexical level.

Next: , Up: Writing style

4.1 Blocks

Next: , Previous: Blocks, Up: Writing style

4.2 Declarations

4.2.1 Alignment

Pointers and references are part of the type, and MUST be put near the type, not near the variable.

     const char* p;  // not `const char *p;'
     std::string& s; // not `std::string &s;'
     void* magic (); // not `void *magic();'

4.2.2 Declarations

Next: , Previous: Declarations, Up: Writing style

4.3 Statements

Next: , Previous: Statements, Up: Writing style

4.4 Expressions

Next: , Previous: Expressions, Up: Writing style

4.5 Control structures

4.5.1 General rules

4.5.2 Loops, general rules

Previous: Control structures, Up: Writing style

4.6 Trailing whitespace

Next: , Previous: Writing style, Up: Top

5 Object Oriented considerations

Next: , Up: Object Oriented considerations

5.1 Lexical Rules

Previous: Lexical Rules, Up: Object Oriented considerations

5.2 Do's and Don'ts

Next: , Previous: Object Oriented considerations, Up: Top

6 Global specifications

Some general considerations about the C++ sources of a project are specified in the following sections.

Next: , Up: Global specifications

6.1 Casts

Next: , Previous: Casts, Up: Global specifications

6.2 Global scope and storage

You SHOULD NOT be using global objects or objects with static storage. Whenever you do, you must be aware that their construction order is subject to the so-called static initialization order fiasco (see this link).

Previous: Global scope and storage, Up: Global specifications

6.3 Code density and documentation

Next: , Previous: Global specifications, Up: Top

7 Project layout

Specifications in this chapter are to be altered (most often relaxed) by the assistants on a per-project basis. When in doubt, follow these guidelines.

Up: Project layout

7.1 Directory structure

This section is identical to the corresponding one described in the C Coding Style.

Note, however, that many people tend to use make tests instead of make check or to put their tests in a directory named test or check whereas it SHOULD be named tests in order to comply with the gnu Coding Standards.

Next: , Previous: Project layout, Up: Top

8 Differences with the C Coding Style

This is a non exhaustive list of the differences between the guidelines provided by this document and that provided by the C Coding Style.

Previous: Differences with the C Coding Style, Up: Top

Index and Table of Contents

Table of Contents