documenting

Just a question ppl always talk about documenting their code i never have and it seems like i do just fine....i comment my code however...is that just as good?
You mean like saving all your code someplace? I do that. Comes in handy sometimes, but it really takes up space.

EDIT: I have this huge library which is 1000 lines long with a bunch of handy functions.
Last edited on
Documenting and commenting is the same things for the most part. Documenting is doing something like. Just depends on how you plan to use it later. If you document by commenting like (this is just a dumb one for a quick example):

1
2
3
4
5
6
7
8
9
/*******************
 *    sum function
 * takes two floats and adds them together
 * returns the value
 *********************/
float sum(float a, float b)
{
      return (a+b);
}


If you plan on others to use your code or such, then you may consider learning to use Doxygen or such as you can make you comments with special formatting and then just run Doxygen on your directory and it will make up html pages for easy look up of your code and how to use each function.
Use a documentation generator like Doxygen and get into the habit of writing documentation comments. You'll pick it up, but the most important things are
1
2
3
4
5
6
7
8
/**
 * \brief Description of the object (class, enum, variable, constant, function, etc.).
 * \param x Description of parameter x (functions and methods).
 * \return Description of return value (functions and methods).
 * \author Name (and e-mail address) of author.
 * \note Note.
 * \warning Warning.
 */

You should look for a list of Doxygen keywords, there are some others that you will want to use.

Unless you're writing a library, you can't stop at code documentation (even for a library, you shouldn't, but if the code documentation is good enough I can usually figure out how to use a library anyway). You should always have some documentation that explains how to actually use your program: describe any command-line arguments, describe the GUI if there is one, describe any commands the user can, um, use, etc.
Last edited on
Topic archived. No new replies allowed.