In an email from UBM Tech this week there was a link to an article titled “A Simple Style for C Programming by Mansi Research“. It was actually authored back on May 2010 by Meetul Kinariwala but appeared this week under the what’s hot section, so I thought I’d take a look [advice to the reader; don’t bother].
The problem with guides like this is that style is a very subjective area (as any parent will tell you how their kids like to point out your lack of style). Programming is no exception and you could argue with C being such a compact language, it suffers more than many other languages.
One of the many good things about the MISRA-C guidelines is that it clearly separated out the issue of style vs. coding guidelines, i.e. [Guidelines for the Use of the C Language in Critical Systems, ISBN 978-1-906400-10-1, page 9]
5.2.2 Process activities expected by MISRA C
It is recognized that a consistent style assists programmers in understanding code written by others. However, since style is a matter for individual organizations, MISRA C does not make any recommendations related purely to programming style. It is expected that local style guides will be developed and used as part of the software development process.
I couldn’t have put it better myself.
Clearly for larger teams a style guide is a useful and important part of the development process.
A whole host of style issues can be addressed with a “pretty printer” tool such as Artistic Style. These simply allow you to define a standard model for items such as ‘{‘ alignment, tab-to-space ratio and spacing within expressions [e.g. if (a&&b) vs. if ( a && b ), etc.].
However there are many style issues that can’t be addressed with automation, for example naming convention. People of a certain age will have been unfortunate enough to have to use Hungarian notation, which, at its roots, had a good underlying principle (embedded type information in the name). That said, Hungarian notation is, in my opinion, an abomination.
One of those coding styles that always make me want to spit feathers is putting a literal on the left of a comparison expression, e.g.
if (10 == var)
I know, you think it’s a great idea as it stops you accidentally writing:
if(var = 10)
Yes it does, but that also tells me you’re not using any form of static analysis tool (e.g. PC-lint, Coverity, QAC, etc.) which means you’ve got much bigger problems that accidentally assigning 10 to the variable!
My major issue is that, for someone who ends up reviewing a lot of other people’s code, it acts as a mental ‘speed bump‘; I wouldn’t say “if ten is equal to var?“‘ I’d say “if var is equal to 10?“, so why write it that way? Surely we want to make code a readable as possible and I’d argue (10 == var) is just ‘bad‘ style.
Probably the biggest issue I regularly come across is that most company coding standards
- do not differentiate between rules that are there for safety/security reasons (e.g. Functions shall not call themselves, either directly or indirectly) and rule purely for style (e.g. for pointer variables place the * close to the variable name not pointer type)
- do not have automation of rule checking; if it’s not autometed it won’t get enforced.
As I’ve already said, I’m not against coding style guidelines, quite the contrary I think, when well done, they aid code readability across a project/company. But what’s really needed is a coding meta-style guide (i.e. a guide to what a coding style guide should address).
For example, a coding style guide should consider the structure of a C file, e.g. ordering items within a file based on some defined criteria, such as:
- Context then definition
- External then Internal
- Public then Private
- Functional grouping
- Type grouping
- Alphabetic sorting
The meta-style-guide tells you that you should consider file structure; the actual-style guide tells you, for you project, how a C file should be structured.
Googling the web hasn’t thrown up any meta-style guides, so here at Feabhas we’re undertaking to develop an open, community driven, meta-style guide. We haven’t defined the best model yet (github, google+, etc.), but as soon as we do I’ll ensure it’s published here.
In the meantime feedback/comments on the meta-guide would be welcome.
UPDATE
I have subsequently come across the following resource that is a great meta-guide C Style: Standards and Guidelines and I highly recommend a visit.
Niall has been designing and programming embedded systems for over 30 years. He has worked in different sectors, including aerospace, telecomms, government and banking.
His current interest lie in IoT Security and Agile for Embedded Systems.
- Navigating Memory in C++: A Guide to Using std::uintptr_t for Address Handling - February 22, 2024
- Embedded Expertise: Beyond Fixed-Size Integers; Exploring Fast and Least Types - January 15, 2024
- Disassembling a Cortex-M raw binary file with Ghidra - December 20, 2022
Co-Founder and Director of Feabhas since 1995.
Niall has been designing and programming embedded systems for over 30 years. He has worked in different sectors, including aerospace, telecomms, government and banking.
His current interest lie in IoT Security and Agile for Embedded Systems.
Goodness - I agree with nearly everything you've had to say. The bad news is that the kind of guide you are attempting would be a nice thing to have, and it will never exist in a "release" form.
There are way too many evangelists of one style or another who will cajole, lobby and launch political campaigns to get their version of the one true way into ALL guides.
Hope your coding projects all go well, but life is too short to bother arguing with religious style zealots.
You could do much better by protesting against a different theocracy , like say Iran, that actually does thing evil enough that it's worth the time to protest.
....JW
Pingback: Sticky Bits » Style vs. Substance in C programming | Balau
I like the idea of starting a conversation on this subject, but I have some doubts about the practical utility of a meta-guideline.
1. Once it’s ready, it needs to be applied on new and existing coding style guides, which are written by many different entities that have to accept the meta-guide value first, and then take the effort to apply it.
2. If the project of writing this meta-guide is community driven, I’m afraid of the “bike shed effect“, where everyone feels entitled to say something because they know their way is right.
My suggestion would be to keep it transparent (read-only to everyone including the rationale), but to not involve everyone on the net on the issue. It’s probably better to ask the right people (in terms of technical skills and cooperation attitude) to participate and keep the number of developers to a manageable number.
Then, once the meta-guide is done (or while it is being written), take existing public code style guides and correct them (or rewrite them) under the meta-guide rules. This can be seen as forking a project, adding your needed features, and similarly you could ask for “pulling” your modifications back into the upstream guide.
Anyway, I'm hoping you come up with something good and successful.
Hi Balau,
Thanks for the feedback, and in reflection I think you're right regarding the "read-only, transparent" model.
Much appriciated
Hi Niall
Another thing (10 == something) says is: I have no tests.
Good article!
I agree with you about making a clear distinction between style and substance. I also believe both are important: a uniform style can save an enormou amounts of time. However, as you say, if the checking is not automatized, then the style will not be followed consistently. Luckily, there are tools that can help both with the style and the substance.
Hi Niall,
As a embedded systems design firm, most of our engineers juggle around a dozen odd coding styles, each of which is generally a proprietary requirement by a different customer. However, when not mandated by a customer, the idea was to use a style which was just simple and concise and which simply addressed our key readability concerns over the years.
MISRA is no doubt an elaborate 143 point evolved standard and we will certainly look at how it can address our needs.
Wishing you lots of success on your undertaking of a new meta-style guide initiative.
P.S. - In best interest of neutrality, let your readers take a neutral judgement on a paper, that very much looks like a trigger for your blog, instead of outright advising against reading it.