Do you guys write code documentation for your C++ Applications?

[RUNNER PRO AGARIO]

When I'm writing a C++ library with a public API, I always write documentation for each function and class using Doxygen. I've seen this in many open source projects as well.

However, when it comes to open source applications, then I generally don't see such documentation. I've looked through many on Github, and while they may have documentation related to structure of the code and usage, they don't seem to have any code documentation. Now my belief is that everything should be documented, so that if I come back to my code in say, a month, I know what I'm doing. But I don't see this practice followed much with open source.

Do you guys write documentation for application code? Why or why not?

[helios]

Now my belief is that everything should be documented, so that if I come back to my code in say, a month, I know what I'm doing.

This is an inappropriate use for documentation.
Can you ensure that the documentation will stay synced with the code at every stage in the development process? If not, then necessarily at one time the documentation for some function will lie about what that function does or how it does it.
The correct solution is to write code that can be understood even without documentation.

There's a different kind of documentation that describes in broad strokes the general architecture of the application. For example it may describe the path the data will follow through the code when an operation is performed, which functions or classes are involved, that sort of thing. Very high level. The point is to give general idea of what to look for if it's necessary to make some change.

[E0p9LyTq]

If I write documentation it is done is broad strokes. What a block of code or function does overall.

I try to make the actual code be self-documenting, choosing easy to understand names for variables, function/class names, etc.

In most instances of public code libraries there is either too much documentation about the code, making it hard to see the overall picture of the classes/functions through the forest of word salad, or too little and I spend hours scratching my head staring at single character named variables/functions without a clue what they are for.

None of the code I write is intended for public use, it is more a personal learning experience with a bit of a hobby thrown in, so I document as little as possible. Just enough to pick up the intent days, weeks or months after putting the project aside.

[RUNNER PRO AGARIO]

I see what you guys mean. And I do write high level documentation. I was just wondering if code documentation is done as well for applications. Thanks for clearing that up.

Now I guess I'm going off on a tangent, but do you guys write function per function, class per class documentation for libraries that have a versioned public API? (I mention versioned since documentation should change with version changes if the API changes)

@FurryGuy, I'm unsure what to make of the second part of your comment. I think that having documentation for every variable is going overboard, but I definitely think every class/function in a public API should have generated (and descriptive) documentation. Many (popular) programming languages and existing C++ libraries do this (such as SFML).

[E0p9LyTq]

I have seen code with every single line of code documented. Sometimes with multiple lines of comments.

Too often the line of code was rewritten at some time in the past and the comment wasn't. So now the comment makes less than zero sense.

There is a fine line between too little and too much documentation.

Do what you think is best.

Be prepared for people to complain there is overly documented code or too little.

[jeremy7878]

of course, yeah. write a Good docs.

but I prefer using GIT It makes everything clear

[RUNNER PRO AGARIO]

jeremy, yeah it is true that version control makes it easier to manage documentation, but I honestly don't feel function per function documentation to be necessary for applications, for the reasons specified above.

[Ganado]

At my work, we do not have documentation for everything, although we do it for some modules/projects. I feel like it's something that should be done more, but the problem is that documentation can be seen as just another dependency/redundancy that can quickly become inaccurate. Even in just some simple script files, I've had to deal with comments going out of date. We of course use version control as well, and that makes it easier, with detailed descriptions of changes we can sort through, but I agree with Runner Pro Agario that that isn't a complete solution.

We do other secondary things that can be seen as a form of documentation. We encourage unit testing to be done. We have a wiki of sorts with guides to explain how to do or change certain features. Again, it's not like we have zero documentation, but there is a point at which it does not become cost-effective to focus on documentation which might not be useful or could just go out of date.

Also, higher-level code is documented less than lower-level code, because higher-level code tends to be more "self-documenting" when written using best practices. But the low-level code that deals with very specific, critical events is documented a lot more in-depth.