C Style: My favorite C programming practices (2014)

Suffice to say: my opinions on this topic have shifted significantly. A decade+ more of programming-in-the-large, and I no longer pay much heed to written-in-prose style guides. Instead, I've found mechanistic "style" enforcement and close-to-live-feedback much more effective for maintaining code quality over time.

A subtext is that I wrote this during a period of work - solo programmer, small company - on a green-field power system microcontroller project; MODBUS comms, CSV data wrangling. I'd opted for C primarily for the appeal of having a codebase I could keep in my head (dependencies included!). There was much in-the-field development, debugging and redeployments, so it was really valuable to have a thin stack, and an easy build process.

So, other than one vendored third-party package, I had total control over that codebase's style. And so, I had the space to consider and evolve my C programming style, reflecting on what I considered was working best for that code.

My personal C code style has since shifted significantly, as well - much more towards older, more-conventional styles.

Still, opinionated, idiosyncratic documents like this - if nothing else - can serve as fun discussion prompts. I'm appreciating all the discussion here!

If speed is a primary concern, you can't tack it on at the end, it needs to be built in architecturally. Benchmarks applied after meeting goals of read/maintainability are only benchmarking the limits of that approach and focus.

They can't capture the results of trying and benchmarking several different fundamental approaches made at the outset in order to best choose the initial direction. In this case "optimisation" is almost happening first.

Sometimes the fastest approach may not be particularly maintainable, and that may be just fine if that component is not expected to require maintaining, eg, a pure C bare-metal in a bespoke and one-off embedded environment.

One thing that I'll strongly quibble with: "Use double rather than float, unless you have a specific reason otherwise".

As a graphics programmer, I've found that single precision will do just fine in the vast majority of cases. I've also found that it's often better to try to make my code work well in the single precision while keeping an eye out for precision loss. Then I can either rewrite my math to try to avoid the precision loss, or selectively use double precision just in the parts where its needed. I think that using double precision from the start is a big hammer that's often unneeded. And using single precision buys you double the number of floats moving through your cache and memory bandwidth compared to using double precision.

Try pasting a long URL into a comment describing a method/problem/solution and you’ll see immediately that it doesn’t fit 77 chars and you cannot wrap it. Then due to your hard limit you’ll invent something like “// see explained.txt:123 for explanation” or maybe “https://shrt.url/f0ob4r” it.

There’s nothing wrong with breaking limits if you do that reasonably, cause most limits have edge cases. It’s (Rule -> Goal X) most of the times, but sometimes it’s (Rule -> Issue). Make it (Solution (breaks Rule) -> Goal X), not (Solution (obeys Rule) -> not (Goal X)).

However, the item to not use unsigned types is vastly stupid! Signed types have far more instances of UB, and in the face of 00UB [1], that is untenable.

It is correct that mixing signed and unsigned is really bad; don't do this.

Instead, use unsigned types for everything, including signed math. Yes, you can simulate two's complement with unsigned types, and you can do it without UB.

On my part, all of my stuff uses unsigned, and when I get a signed type from the outside, the first thing I do is convert it safely, so I don't mix the two.

This does mean you have to be careful in some ways. For example, when casting a "signed" type to a larger "signed" type, you need to explicitly check the sign bit and fill the extension with that bit.

And yes, you need to use functions for math, which can be ugly. But you can make them static inline in a header so that they will be inlined.

The result is that my code isn't subject to 00UB nearly as much.

[1]: https://gavinhoward.com/2023/08/the-scourge-of-00ub/

I used to agree with this but I have moved away from compound literals entirely except for global statics/const definitions.

Having a variable and explicit:

  foo.x = whatever;
  foo.y = something_else;

This is one of the silliest practices to still be enforced or even considered in 2024. “Readers” should get a modern IDE/text editor and/or modern hardware.

I'm more like: Always use tabs, never use space. Code doesn't need to be "aligned" it's not some ASCIIart masterpiece...

One tab means one indentation level and if your taste is to have tabs of pi chars wide, nice! But it won't mess my code

Read the type for all the below right-to-left, substituting the word "pointer" for "*".

  int long long unsigned wibble; // unsigned long long int
  double const *long_number; // pointer to a const double
  double volatile * const immutable_pointer; // immutable pointer to a volatile double

by contrast, this document is largely motherhood and apple pie — and where it isn't (e.g., when it advocates titlecasing struct types or never typedeffing primitive types), i often think it's wrong. 'Write assertions to meaningfully crash your program before it does something stupid, ... to prevent a security vulnerability' is especially wrong; one of the major features of the standard assert() macro is that it's turned off in release builds!

the named-arguments macro hack is an example of the kind of thing i was most hoping to find in here

if you write something like this, don't dilute whatever value it may have with your opinions about tabs vs. spaces, line length, what natural language to write your comments and identifiers in, include guards, how many blank lines to put between functions, etc. these have been debated to death, and you're unlikely to have any brilliant insights about them that other people will be happy to have read

I'm sorry, I just cannot do this. I start to feel somewhat guity after 300 characters but 80 feels like an Atari 800.

Tabs are always correct, IF spaces are never used instead. One tab, for one level of indent. Adjust to preference.

Alas, I don't think there's a standard way of specifying...

// kate: space-indent off; indent-width 8; tab-width 8; mixedindent off; indent-mode tab;

Similarly, // comments should be preferred, but /* comments */ are acceptable at the top of large function blocks for large blobs of comments. Judicious / sparing use as the key idea to make it worth the exceptions if commenting out large blocks during tests or refactors.

Just one (personal) stuff : Stick to 80 columns... Sorry, no ! :)

Why not? Do people really care about porting their toy project to another compiler? If portability is a goal, avoid extensions, but not all projects need to be portable.

I'm writing an Operating System, and I do not care it if compiles on Clang or MSVC. GCC has been around for decades, it is a safe bet.

Can’t a modern compiler do that already? Didn’t google but seems an obvious compiler feature at the very least behind a warning flag.

Absolute agreement

  * Always develop and compile with all warnings (and more) on
  * #include the definition of everything you use
  * Provide include guards for all headers to prevent double inclusion
  * Always comment `#endif`s of large conditional sections
  * Declare variables as late as possible
  * Be consistent in your variable names across functions
  * Minimize the scope of variables
  * Use `assert` everywhere your program would fail otherwise
  * Repeat `assert` calls; don't `&&` them together
  * C isn't object-oriented, and you shouldn't pretend it is

  * Use `//` comments everywhere, never `/* ... */`
  * Comment non-standard-library `#include`s to say what symbols you use from them
  * No global or static variables if you can help it (you probably can)
  * Minimize what you expose; declare top-level names static where you can
  * Use `double` rather than `float`, unless you have a specific reason otherwise
  * Avoid non-pure or non-trivial function calls in expressions
  * Simple constant expressions can be easier to read than variables
  * Initialize strings as arrays, and use sizeof for byte size
  * Where possible, use `sizeof` on the variable; not the type
  * Document your struct invariants, and provide invariant checkers
  * Avoid `void *` because it harms type safety
  * If you have a `void *`, assign it to a typed variable as soon as possible
  * Only use pointers in structs for nullity, dynamic arrays or incomplete types
  * Avoid getters and setters

  * Don't be afraid of short variable names [if the scope fits on a screen]
  * Explicitly compare values; don't rely on truthiness
    [unless values themselves are boolean]
  * Use parentheses for expressions where the operator precedence isn't obvious
    [but `&foo->bar` *is* obvious]
  * Separate functions and struct definitions with two lines
    [can use comments instead]
  * If a macro is specific to a function, `#define` it in the body [and `#undef` ASAP]
  * Only typedef structs; never basic types or pointers
    [or make them distinct enough, but ISO C stole a `_t` suffix]

  * Use GCC's and Clang's `-M` to automatically generate object file dependencies
  * Avoid unified headers
  * Immutability saves lives: use `const` everywhere you can
  * Use `bool` from `stdbool.h` whenever you have a boolean value
  * Avoid unsigned types because the integer conversion rules are complicated
  * Prefer compound literals to superfluous variables
  * Never use array syntax for function arguments definitions
  * Don't use variable-length arrays
  * Use C11's anonymous structs and unions rather mutually-exclusive fields
  * Give structs TitleCase names, and typedef them
  * Never begin names with `_` or end them with `_t`: they're reserved for standards
  * Only use pointer arguments for nullity, arrays or modifications
  * Prefer to return a value rather than modifying pointers
  * Always use designated initializers in struct literals

  * Write to the most modern standard you can [we have no choice for many cases]
  * Program in American English [only applicable for native speakers]

  * Don't write argument names in function prototypes if they just repeat the type
    [such case is very, very rare]
  * Use `+= 1` and `-= 1` over `++` and `--`
    [`++`/`--` should be read as succ/pred and should be exclusively used for pointers]
  * Don't use `switch`, and avoid complicated conditionals
    [switch is okay once you have enabled enough warnings]
  * Only upper-case a macro if will act differently than a function call
    [agreed in principle, but should define "differently" more broadly]
  * Always prefer array indexing over pointer arithmetic
    [and then you will be biten by index variable types, remember `ptrdiff_t`]

  * We can't get tabs right, so use spaces everywhere
    [as long as mechanically enforcable, the choice itself is irrelevant]
  * Always put `const` on the right and read types right-to-left [too eyesore]
  * Use one line per variable definition; don't bunch same types together
    [will agree with some significant exceptions though]
  * Never change state within an expression (e.g. with assignments or `++`)
    [absolutely avoid functions, but `++` has its uses]
  * Always use brackets, even for single-statement block
    [rather a read-write trade-off; this may make some codes harder to read]
  * Never use or provide macros that wrap control structures like `for`
    [the example is very tame in comparison to actually problematic macros]
  * Don't typecast unless you have to (you probably don't)
    [while many typecasts can be easily removed, excess doesn't do actual harm]
  * Give enums `UPPERCASE_SNAKE` names, and lowercase their values
    [I would rather avoid enums for various reasons]
  * Use structs to name functions' optional arguments
    [maybe the author tried to say "avoid too many arguments" instead?]
  * If you're providing allocation and free functions only for a struct member,
    allocate memory for the whole struct
    [that complicates using struct as a value]

  * Never have more than 79 characters per line
    [100 or 120 do work equally well, you do need some limit though]
  * Define a constant for the size of every enum
    [would imply that all enum values are sequential, and that's not true!]