I’m looking to create some detailed documentation for my team’s code (to better teach new programmers), and I was wondering if anyone has seen any documentation formats/tools that they really like. Of course doxygen is awesome, but I would like to also have something that really explains a lot of the concepts used in the code. I suppose I could just write a long Word document if all else fails. Thanks for your input!
1 Like
Regardless of the specific format you settle upon, I recommend that you keep your documentation as close to the code as possible. Classes should have an explanation of what they’re for. Same with methods. Make sure that you document anything unobvious about parameters and returns, especially units (e.g. metres, degrees, RPM). Same for constants. I’ve seen entire codebases that give no clue about what unit they’re using.
Code-level documentation is not enough, of course, and you still need to explain important things about the architecture. I still recommend sticking close to the code; if you’re using Github, use markdown files that can be branched, modified, and tracked alongside the code.
2 Likes
Sphinx is great, or anything with restructured text or markdown-like formats. Overall, you documentation should be in source control, same as code.
100% this. I highly recommend using the units library wherever possible if you’re using C++. We used it extensively this year and it’s been great being able to mix and match units to align to external sources without worrying about forgetting a manual conversion. It would be worth it just for radians/degrees.
2 Likes
Absolutely, 100% this. Documentation has to be treated as source; it is of equal importance to the actual code.
Even professional organizations struggle with this; I’ve been trying to get my workplace to move to source-controlled documentation for several months now, and it is moving, but slowly…
We use javadocs for commenting on methods. It’s super helpful to be able to hover over methods from our helper classes to see how things work without reading all of the code.
This topic was automatically closed 365 days after the last reply. New replies are no longer allowed.