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.
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¶
- 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¶
Namespaces and Modules¶
Templates and Genericity¶
Error handling and Exceptions¶
STL: Containers¶
STL: Algorithms¶
Type Safety¶
Modern C++¶
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