Post History

Source: https://writers.stackexchange.com/q/36232
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly beneficial. My question is not how to add documentation, but when. And what to add. Doxygen seems to be the preferred method although I'm sure there are others, but all the tutorials and advice out there seem to describe how. It's usually more about the parser than anything else.

Some of what I have picked up over the past few months include:

- Self-documentation: a lot of C++ naming revolves around explicitly stating what is happening in the code base itself. Is this what I should strive for? Should good code be self-explanatory at every level?

- Documentation requires maintenance too: I have read caveats that warn against excessive documentation as when your software is updated so must your documentation.

- I've also read that comments should explain why you do something in your code. Not what you do. I do understand that a comment and documentation aren't necessarily the same thing, so I am still uncertain when and what to document.

I don't want to be lazy and avoid good documentation, but I also don't want to weigh down my software with overwrought bogs of difficult to maintain and absurdly obvious descriptions of my code. Any sort of guidance here would be greatly appreciated. Even some examples of what you would consider good documentation could benefit me.

Original score: 14