C++ is definitely a language that has Lots of Ways to do It – kind of like Perl’s TIMTOWTSAC. A consequence is that when writing code, you need to think about which way to do things. When context-switching between projects, employers, or what-have-you, you may have to context-switch preferences for which way is preferred. Guidelines can help, and I love them.
I do love
clang-tidy (and before that,
because they help apply automated guidelines that make a choice as
to which way to do things like
- place braces
- leave spaces in template arguments
- order includes
- write names of types
- avoid bug-prone constructs
Way back in the days of the English Breakfast Network (like, 2009) we wrote some tools to flag bug-prone constructs in KDE code, and encouraged people to clean those up. Nowadays other tools do a much better job.
I’m a big fan of auto-format-on-save within an IDE. That way I can type, copy-paste, futz around and have things cleaned up automatically. At $WORK, I use vscode and it does a good job of running tools in a remote container for formatting – as long as the file isn’t some 50000-line monstrosity, that is. I don’t know if KDevelop can do it, but my muscle memory on a Free Software platform switches to Konsole regularly to run formatting scripts, so I have never really investigated KDevelop’s capabilities there.
Toot me at kdedude on fosstodon.org if you know about KDevelop.
For Calamares I’ve been following the coding style
laid down for that project for seven years. I still don’t like it,
but it is automated (
ci/calamaresstyle does the job) and reasonably
well-described, so it is an automated guideline.
For $WORK, we have a fairly short
.clang-format file – short because
it doesn’t do anything weird, it’s basically “this other style, but put
braces on lines on their own and move
* to the other side”. Again,
I think the most important part of this kind of automated guidelines is that reading code doesn’t take additional effort: the style is fixed, so there are zero surprises when reading code from Jane, Jim, or Joan.
Outside of what tools can apply automatically, there are still a lot of guidelines – rules-of-thumb, things-to-keep-in-mind – that can apply to any codebase. Not a week goes by that I don’t cite Kate Gregory’s Naming is Hard, but even when writing down the name of a Turdus migratorius, maybe there are variations to consider.
There are other cursed naming schemes possible, for sure. Let’s not go there.
When to use
struct and when to use
class in C++? That’s another thing you
could argue about (in the language, the only differences is the default access
specifier, but using one or the other can convey meaning to other developers).
For Free Software examples, consider Qt and KDE, which use a distinctive
letter as the start of most class names (probably due to the lack of namespace
support in the pre-standardization C++ era), which use camelCase for
function names, etc .. If you spot
setText you know it’s a function,
QLabel is a class, obviously. There’s no
Label accessor, no
get_text function either, and this consistency makes reading code
At $WORK there’s a team of developers, and we task-switch a bit. One of the things we actively do is discuss coding style, so that reading other people’s code is as unsurprising as possible. We try to pack some extra meaning into names if we can.
The consequence of having these non-automated guidelines is that we regularly pick them up to discuss readability (e.g. when doing a review of new code) and we discuss and adapt the guidelines with some regularity – usually when some new and unexpected construct shows up. Recently we ended up with a long discussion about unmoveable objects and piecewise-construction, for instance.
The guidelines we use are now published by colleague Jan Wilmans, in a guidelines repository. I might not like all of the guidelines, but they save me thinking about which way to do things all the time, and that simplifies my life and improves the effectiveness of communication with my colleagues.
Write guidelines. Automate what you can. Document what you can’t. Make communication through code consistent, unsurprising, and readable. Collaborate. Follow existing style when possible.
The guidelines that Calamares uses, or my $WORK, might not be for you – write down your own. Fight for improvements. Write the simplest, most elegant, most readable and understandable code you can.