IceCube Coding Standards

../_images/brazil.jpg

This is the third draft of the IceCube C++ Coding Standards. The first draft was provided by Thomas Burgess, the second by Erik Blaufuss. The third is being expanded by the community.

Introduction

These are coding standards and recommendations for developers of IceCube software in C++ and Python. There is a companion document for Library Standards.

This document refers primarily to offline software (including IceTray, Dataclasses, Simulation and the event viewer). Users are encouraged to write their own private software to these standards, to make future code maintence and the adoption of private code for production use easier.

Python Coding Standards

Python coding standards follow the recommendations set forth in PEP 0008. Where they cause conflict, the C++ coding standards outlined below, take precedence.

C Coding Standards

The use of pure C is strongly discouraged. This is not a statement about the language, it’s simply a choice we have to make based on the limited resources available. We have one compiled language (C++) and one interpreted (Python) that covers everything we need. We strive to ensure that all production code is accessible to every member. C++ is no longer “C with classes” but arguably a separate language. At the very least, coding styles differ greatly between the two communities and we have our hands full with the two official languages we already have.

Should you find it necessary to write something in pure C, we ask that you follow the Linux kernel coding style.

Linux Kernel Coding Style

C++ Coding Standards

Good coding standards offer many interrelated advantages:

  • Improved code quality: Encouranging developers to do the right things in a consistent way directly works to improve software quality and maintainability.

  • Faster development: Developers dont need to always make decisions starting from first principles.

  • Better Teamwork: They help reduce needless debates on inconsequential issues and make it easier for teammates to read and maintain each other’s code.

  • Uniformity in the right dimension: This frees developers to be creative in directions that matter.

Code reviews will make constant reference to C++ Coding Standards [1], by Herb Sutter and Andrei Alexandrescu. If you submit code that gets reviewed, you should have access to a copy: reviewers will refer to the book, and everybody will save time if you can read the full details/explanations yourself.

This document borrows pieces from the book’s structure, and you will find direct quotes from the book throughout (like the opening paragraph of this section). Each of the headings below corresponds to a several-page long chapter in the book, where one can find Sutter’s treatment, so look there for more information. Icecube-specific elaborations, modifications, and excerpts from code reviews are found here. You are not expected to memorize them or to submit code in full compliance with every single rule, as these are goals to strive for, and many are achievably only in degree. Do your best, and we will refer to this document in reviews.

Organizational and Policy Issues

Design Style

Coding Style

Functions and Operators

Class Design and Inheritance

Construction, Destruction, and Copying

Namespaces and Modules

Templates and Genericity

Error handling and Exceptions

STL: Containers

STL: Algorithms

Type Safety

Modern C++