I'm writing my first real large application in C, and I wanted to ask the more experience C/C++ programmers something:

Do you provide documentation for your code, even if it is just application code? (That is, not libraries.) I don't mean end-user documentation, but documentation just for helping programmers understand the code.

And if so, what program do you prefer to use for auto-generating the documentation (Doxygen, etc...)?

When I programmed in Perl I tried to document /everything/ in the code using embedded POD. But there is going to be a lot of code in my C project, and I'm trying to decide what is practical and what is really useful to other programmers viewing my source code.

Hi CoderMan!

I prefer to use doxygen. In my opinion the best variant for C code. And certainly clear comments in a code.

Use descriptive variable names, avoid cryptic or deliberately obtuse constructions, and comment liberally - but usefully.

I generally assume that I'll be maintaining my own code and when I look at it 6 months from now I'll have no idea what I did or why. So my comments, variable names, and function names will reflect that.

Personally, I've found that documenting code helps me not only understand my own code later, but I also put my ideas in order before coding. Yes, I document method signatures before actually writing their bodies. A good advise is to document what values are valid for parameters and the meaning of return values (e.g. do 0, -1 or NULL mean error?)

documentation is only useful when it's up to date.

assuming a non trivial app,
what i do is no comments until it's finished.
then, while fresh, spend a whole day documenting.
take it as a serious task.
then a week or so later look again and check it makes sense
when not so fresh.

I would say, for me, it's better to have a big block
at the top of a file describing what the module does.
(Assuming you split your app up logically)
inputs outputs assumptions.
not too many comments littering the code itself.


works for me.

Like many others, I have no idea how my code works after six months. Mostly I do understand what it does.

I comment my functions and code blocks before I write the code to explain to myself what I do and why. Then I implement the code from this text. Since usually the algorithm doesn't change while bug fixing so the comment doesn't get outdated.

And yes, unless the name is very descriptive, I write down an explanation of the parameter list. fact(i) doesn't need that, but more complicated functions do.

jlinkels

One very useful insight I heard somewhere is that you cannot teach people how your code works with comments; therefore, don't try to. Do your best through useful symbol names and readable formatting.

My comments are generally to remind me of why I've done something, or to remind me not to make what I think is a bug correction to something odd looking, yet intentional. With a large application, there really isn't any hope for someone to understand it just by the source code. UML diagrams are probably more appropriate for that, in which case you might write a maintainers' guide if you really want others to understand your code.

Like jlinkels, I often find myself relearning my own projects after several months away from them. That's rarely a result of poor commenting, however. The complex structure, most of which can't be communicated in UTF-8, is generally what I need to relearn. A well-planned and logical structure should be intuitive for you to remember, though, so the structure of your source tree, etc. should reflect it accordingly.

Documentation goes far beyond commenting. Not only should the non-trivial text of your source documents be self-documenting, but every aspect of the package you distribute it in should communicate something useful about it.
ta0kira

I left coding in C++ around 7 years ago (when I moved to Java).

But, one thumb rule when writing any large or production ready application, in any language, is to write plenty of documentation into your code (within comments ofcourse!)
This ensures that a couple of months later when you (or any other developer who has replaced you) takes a look at the code - he/she will be able to understand what you were thinking when you wrote that code and that'll help him/her complete her work much faster!

This is how I do it, though if I'm forced to write something obscure I might put a one line/footnote comment in for a reminder, so that when I do go back and document, I know exactly why I did it.

Doxygen is nice, also.

(sorry, repeat)

I have a better way to document c/c++
You need not to learn nothing ( for dosxgen, you have to follow the format)
What you need is to add comment as much as u can.

see http://sites.google.com/site/jqbsx3/, there are some examples.

If you want other projects, give me a message.