EPITA Programming style standard


Up: (dir)

EPITA C99 Coding Style Standard

This document is intended to uniformize the coding styles of EPITA engineering students during their second term.

Covered topics:

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

During the second period, all submitted projects must comply exactly with the standard; any infringement causes the mark to be multiplied by 0.

--- The Detailed Node Listing ---

How to read this document

Naming conventions

Preprocessor-level specifications

Writing style

Global specifications

Project layout

Differences with previous versions

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

This standard uses 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:

MUST
This word, or the terms REQUIRED or SHALL, mean that the definition is an absolute requirement of the specification.
MUST NOT
This phrase, or the terms PROHIBITED or SHALL NOT, mean that the definition is an absolute prohibition of the specification.
SHOULD
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 understod and carefully weighted before choosing a different course.
SHOULD NOT
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.
MAY
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 confuse the intention and extension of this document.

The intention is to limit obfuscation abilities of certain students with prior C experience, and uniformize 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 standard 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 examples

Examples of this standard 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, or they might “magically” appear in new revisions.


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


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

2.2 Name capitalization


Previous: Name capitalization, Up: Naming conventions

2.3 Name prefixes


Next: , Previous: Naming conventions, Up: Top

3 Preprocessor-level specifications

The global layout of files, and sections of code pertaining to the C preprocessor, 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

For additional specifications about comments, see File layout and Global specifications.


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 behaviour at the language level. They cover various aspects of C constructs.


Next: , Up: Writing style

4.1 Blocks


Next: , Previous: Blocks, Up: Writing style

4.2 Structures variables and declarations

4.2.1 Alignment

4.2.2 Declarations


Next: , Previous: Structures variables and 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 while and do ... while

4.5.3 for

Exceptions to other specifications (See Statements, see Structures variables and declarations) can be found in this section.

4.5.4 Loops, general rules

4.5.5 The switch construct


Previous: Control structures, Up: Writing style

4.6 Trailing whitespace


Next: , Previous: Writing style, Up: Top

5 Global specifications

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


Next: , Up: Global specifications

5.1 Casts


Next: , Previous: Casts, Up: Global specifications

5.2 Functions and prototyping


Next: , Previous: Functions and prototyping, Up: Global specifications

5.3 Global scope and storage


Previous: Global scope and storage, Up: Global specifications

5.4 Code density and documentation


Next: , Previous: Global specifications, Up: Top

6 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 the standard.


Next: , Up: Project layout

6.1 Directory structure

Each project sources MUST be delivered in a directory, the name of which shall be announced in advance by the assistants. In addition to the usual source files, and without additional specification, it SHOULD contain a number of additional files:

AUTHORS
This file MUST contain the authors' names, one per line. Each line MUST contain an asterisk, then a login name. The first name to appear is considered as the head of the project.

Rationale: this file is to be grep'ed over with a

           ^\* \([a-z-][a-z-]*_[a-zA-Z0-9_-]\).*$
     

regexp pattern to extract login names.

It is especially important to note that this specifications allows for documenting a project by using actual text in the AUTHORS file: the regexp will only extract the relevant information. For example, consider the following text:

          

This project was written with the help of: * foo_b (Foo Bar), main developer; * baz_y (Baz Yay), code consultant; * chiche_f (Chichery Florent), coffee maker; Many thanks to them for their contribution to the project.

Because the regex only matches the relevant information, it constitutes a valid AUTHORS file.


configure
When the project contract allows so, and only then, the script configure is automatically run before running the make command. It MAY create or modify files in the current directory or subdirectories, but MUST NOT expect to be run from a particular location.

Rationale: allow for site configuration with Autoconf or similar tools.


Makefile*
Unless explicitly forbidden, the project directory MAY contain an arbitrary number of files with names derived from “Makefile”. These files are optional, although a Makefile MUST be present at the time the command make is run.

Rationale: the Makefile may include Makefile-rules.make or similar files for architecture-dependent compilation options.


Previous: Directory structure, Up: Project layout

6.2 Makefiles and compilation rules


Next: , Previous: Project layout, Up: Top

7 Differences with previous versions


Next: , Up: Differences with previous versions

7.1 Differences with the legacy version

The 2002 document was intended to supercede the legacy norme, first written in (??), and last updated in October, 2000.

It was based on the previous version, adding finer distinctions between requirements and recommendations, updating previous specifications and adding new ones.

Here is a summary of the major changes:

In addition to these changes, the structure of the standard itself has been rearranged, and an index was added.


Next: , Previous: Differences with the legacy version, Up: Differences with previous versions

7.2 Differences with year 2002

Starting with 2003, the assistants decided to revert to a short specification written in french, for readability convenience.

The english document you are now reading was a complement that could optionnally used as a substitute.

Here is a summary of the major changes:


Next: , Previous: Differences with year 2002, Up: Differences with previous versions

7.3 Differences with year 2003

Starting from the year 2004, this english version is the official specification document used.

The major changes are:


Next: , Previous: Differences with year 2003, Up: Differences with previous versions

7.4 Differences with year 2004

No significant changes: minor corrections to some examples.


Next: , Previous: Differences with year 2004, Up: Differences with previous versions

7.5 Differences with year 2005

The following changes were introduced during the year 2006.

Here is a summary of the major changes. These modifications were introduced to make the whole coding style standard more coherent.


Next: , Previous: Differences with year 2005, Up: Differences with previous versions

7.6 Differences with year 2006

The following changes were introduced during the year 2007.

Here is a summary of the major changes.

Other minor changes this year include:


Previous: Differences with year 2006, Up: Differences with previous versions

7.7 Differences with the ANSI C Coding Style


Next: , Up: Differences with the ANSI C Coding Style

7.7.1 Comments

see Comment layout


Next: , Previous: Comments changes, Up: Differences with the ANSI C Coding Style

7.7.2 Variable declarations

see Structures variables and declarations


Next: , Previous: Variable declaration changes, Up: Differences with the ANSI C Coding Style

7.7.3 For construct

see Control structures


Next: , Previous: For changes, Up: Differences with the ANSI C Coding Style

7.7.4 Prototypes

see Functions and prototyping


Previous: Function changes, Up: Differences with the ANSI C Coding Style

7.7.5 Compilation flags

see Project layout


Previous: Differences with previous versions, Up: Top

Index and Table of Contents

Table of Contents