what are you using for documenting code?

Doxygeing cubeIDE generated code?

Cube generates only few "well known" files. Usually most of the code does not come from Cube, you can do anything you like there.

Even the opposite - the generated files have dense doxygen garbage, most of which I eventually delete.

> Just a pdf explaning some of the abstractions

Why not? this does not interfere with doxygen (or lack of it). OTOH doxygen can include external picture files into output. A picture is worth <many> words.

my code speaks for itself, no need for comments

The only programmers who believe that are the ones dumping years of undocumented code on their successor, before disappearing forever more into the night. It's a great way to rationalize away the guilt of dumping laziness onto the backs of the unsuspecting.

Just a pdf explaining some of the abstractions

Sure, two pages should be more than enough for 50KLOC of code.

Doxygen

It's a great way to standardize the comments embedded in the code. Not so great if you need to figure out how it all fits together...assuming the Doxygen comments are not just as cryptic as the code.

What I've always done is embed real comments in the code. That means a file header explaining what the module does, descriptions for all globals, headers for each procedure, including parameters, and finally line by line comments aligned on the right explaining the train of thought. Assembly language old-timers will recognize the format immediately.

Aside from commenting the code I always prepared a technical reference manual, organized into a hardware section, which explains the major blocks of electronic components, followed by a software section detailing the code modules, how they relate to the hardware, and how data passes from application layer, the protocol stacks, and down to the device driver layer.

A lot of work? Sure, but this was for products with 15+ year lifetimes spread over several generations of maintainers. For a throwaway product, the "self-documenting code" approach is well suited for a support life of two years at a call center in Mumbai.

Remember, it's not just the next guy who's going to maintain the code, the documentation is also for the customer support group. Every issue explained in the manual is one less escalated support call the programmer has to resolve.

I've also been on the receiving side of large, undocumented software projects. All that time saved by not commenting or documenting? The bill comes due when weeks, or months, are needed to reverse engineer spaghetti code that is supposed to be self-evident.

If pressed I might even admit to shouting matches with the previous programmers concerning accusations of incompetency. So yeah, it's a sensitive subject. Day one on a new job, handed a 100KLOC major company software tool to maintain, and it comes with precisely two pages of documentation concerning one particular TCP packet structure. Comments in code? No need, the variable names explain everything...

At least you're asking the right questions. My suggestion, place yourself at the receiving end, assume no knowledge of the project and no resources to consult other than what you provide. What would you want to see?

Jack Peacock

>>"my code speaks for itself, no need for comments"

I think most code needs some comments, but clear and self-contained code, shouldn't need line-by-line commentary stating the obvious. I can sight-read code, I can't understand intent..

Vast documents separate from the code tend not to be read, people tend to be focused on the problem at hand, and want to go straight to that. Document structures, and expectations with those. Keep stuff localized and compartmentalized as much as possible.

People doing care taking work tend to be there to put out fires, and fix real specific problems. There are a lot of people complaining and looking for a quick fix, so focus on what they might need to know in a hurry, follow that with more detail.

Code should be readable. Clean and consistent style and indenting. People can have strong views on how that should look like, but there are tools to actually reformat to whatever they want, and also the act of reformatting manually to one's own style can force neural path ways to be traversed.

Where code sections spans multiple screen pages, commentary on what a brace closes can help when skimming later.

Avoid uses of globals and dumb variable / function labeling.

Generally a good explanation of the goals and function of the following code.

Commentary on any quirky behaviour or expectations, or the software or hardware.

If I've had to debug something, and code was changed, and explanation and date are helpful to line up with other correspondence or reports.

I put in thoughts about what will and will not be seen at a given point, and things I know it won't handle without more thought. And the pitfalls I see.

I also add in comments about who asked for a particular function, settings, or code change, and I perhaps leave an audit trail of those as the settings change/evolve based, especially when I expect a circular conversation about how something should work, and about how the HW/SW actually behave vs the person who might not.

Above all have some narrative, even if it's with your future self. Solid code has a surprisingly long shelf-life.

IDE's have become better over the years, but lack consistency, I like having good static analysis tools when trying to understand others code, especially if it spans hundreds of directories, and thousands of files and functions. A least some of them can chart relationships really well, some of these might be good for generating a good top level overview. Good cross-referencing can help to see how many places use a function, and where those are. It helps understand the magnitude of the danger from changing something that looks otherwise innocuous.

I use lots of comments in the source files.

Surely not for the simple / obvious stuff, but especially as TDL said to explain intent.

I never did very complex programming, mostly for 8-bit controllers, but also for FPGAs.

And being the only one responsible for that part in our company for many devices, I found that after a few years I forgot why I did what, so commenting got much better over the years...

And I think that important info should be in the source files, it's just too cumbersome to open another document where you have to look for the explanations.

That said, what I do is:

• lots of comments in the source files
• a word / pdf document explaining some more stuff, especially for the user or the guys doing the PC host side - they actually only need the "interface" but I put some "firmware explained" in there, too