IceCube Coding Standards

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

• I3 Prefix Convention
• Compile cleanly at high warning levels
• Use a version control system
• Invest in code reviews
• Temporary Test Directories

Design Style

• Don’t Optimize Prematurely
• Minimize Global and Shared Data

Coding Style

• Always Use Curly Braces for Control Statements
• Declare variables as locally as possible.
• Make header files self-sufficient.
• Always write internal #include guards. Never write external #include guards.

Functions and Operators

• Take parameters appropriately by value, (smart) pointer, or reference.
• Don’t write code that depends on the order of evaluation of function arguments

Class Design and Inheritance

• Be clear what kind of class you’re writing.
• Prefer composition to inheritance
• Avoid inheriting from classes that were not designed to be base classes
• Consider making virtual functions non-public, and public functions non-virtual
• Avoid Providing Implicit Conversions
• Don’t give away your internals
• Make data members private, except in behaviorless aggregates (C-style structs)
• Pimpl Judiciously
• Prefer Writing Non-member Non-friend Functions
• Always provide new and delete together
• If you Provide Any Class-Specific new, Provide All of the Standard Forms (plain, in-place, and nothrow)

Construction, Destruction, and Copying

• Define and initialize member variables in the same order

Namespaces and Modules

• Don’t write namespace using in a header file or before and #include

Templates and Genericity

• Don’t write unintentionally nongeneric code
• Blend static and dynamic polymorphism judiciously
• Use auto
• Lambda Expressions

Error handling and Exceptions

• Assert liberally to document internal assumptions and invariants

STL: Containers

• Use vector by default
• Use std::vector and std::string instead of arrays
• Use vector (and string::c_str) to exchange data with non-C++ APIs.
• Store only values and smart pointers in containers

STL: Algorithms

• Use a checked STL implementation

Type Safety

• Don’t use C-style casts

Modern C++

• Prefer alias declaration over typedef
• Use nullptr instead of 0 and NULL
• Smart pointers

Useful links

Bjarne Stroustrup’s C++ pages <https://www.stroustrup.com/>

The pages of the creator of C++

Effective C++ <https://www.aristeia.com/books.html>

Effective C++ and More Effective C++ contains many very useful items for C++ programmers.

C/C++ reference <https://www.cppreference.com/>

General C/C++, standard C libraries, C++ I/0, strings and STL reference.

C++ FAQ lite <http://www.parashift.com/c++-faq-lite/>

Many useful answers on most C++ topics

C++ Notes <http://www.fredosaurus.com/notes-cpp/index.html>

Small useful examples illustrating basic C++ usage.

Doxygen <https://doxygen.nl>

Generates code documentation from source code comments

Also handy for C++ programming GCC <http://www.gnu.org/software/gcc/>

GNU Compiler Collection - many compilers, including the g++ C++ compiler!

Footnotes

[1]

The C++ Coding Standards homepage can be found at http://www.gotw.ca/publications/c++cs.htm