I’ve tried to contribute to some larger open source projects, but the lack of architectural documentation & any form of future plans have quickly descending in to trying to find a black cat in a coal cellar. And in at least two instances, one a major contributor to radio, the academic C++ techniques make moving over the code base to trace inheritance so you can figure out what is actually being called laborious & tiring.

So CDD is good – for the why, the context & the detailed/nuanced stuff – and keeping files such that they don’t need more than a handful of screenfuls to navigate. But the first and most important docs are the CDD on the goal, objectives, architecture, code map (how things are divided up & where they are) and, as required, how it all hangs together.

I’ll use Doxygen to document the header file for public facing libraries but I will let it slide when I am the single maintainer of the project. The more exotic the technology is, the more verbose my comments will be, for example this SD card driver:
https://github.com/piconomix/px-fwlib/blob/master/devices/mem/inc/px_sd.h
https://github.com/piconomix/px-fwlib/blob/master/devices/mem/src/px_sd.c

Here’s the generated Doxygen page:
https://piconomix.com/px-fwlib/group___p_x___s_d.html

Sometimes I will even use a bit of ASCII art to visually document a situation:
https://github.com/piconomix/px-fwlib/blob/master/utils/src/px_ring_buf.c#L91-L103

I prefer to use ST’s low level drivers but the function names are not clear and obvious so I will use comments to say in plain language what it does, for example this function to initialize the clocks:
https://github.com/piconomix/px-fwlib/blob/master/boards/arm/stm32/st_nucleo64_l053/src/px_board.c#L54-L119

It’s an ever evolving art for me. It’s tricky to get the balance just right so that it’s clear and concise and not cryptic or overly verbose.

Ripe / mature not bury, so “ripe it in the subconscious”

To respectfully disagree – and I’m a hobbyist indie game dev, mind you – I like knowing that my programming is working and do get quite excited when I stomp a particular bug. Of course, I’m also autistic so maybe it’s just a hyperfocus thing. But I agree wholeheartedly with this.

And if you want evidence that crappy profit-driven development leads to disaster down the line (in game dev at least), might I point one towards games as a service? Oh boy. That scene is a dumpster fire now.

I recommend you learn how to refactor code.

Then, take time when reading “headache-inducing” code to isolate those confusing chunks. Use the Extract Method refactoring process to move a small tangled bit into its own method, and give that method a descriptive, meaningful name. Also write unit tests for it, proving it does what you think; as a side benefit tests also provide examples to future maintainers how to use the functions. Repeat until the whole block of code explains what it does, and you have tests that prove it.

It’s only a little slower than writing comments and the resulting code is self-documented, which is a whole lot more valuable the next time it needs to be understood.

Of course this approach doesn’t always scale well down to bit manipulation logic buried inside device drivers or other code with super-high performance requirements. But for the majority of code you encounter readable, correctly performing code is far more important than fast code hiding subtle bugs.

Then each file has a comment saying broadly what it contains, and each function etc. has a comment- ideally formatted so as to make sense to any IDE or document generator- describing purpose, parameters and return value; ideally each (public) type or variable would have something similar, but it’s not usually realistic to extend this to individual fields.