How To Document Your Code

How to document your code

How to document your code

Many programmers don't know what to write in code documentation .

Common advice is "write what you'd want to see if you were reading the code“.

I'm going to use the " how , when , where and why ; what , which and who ?“ questions of documenting your code.

What does it do?

This is the most important question.

What does the program do ?

If I'm trying to fix a bug report that says "it doesn't [foo] the bar," I need to know if the bar is supposed to be [fooed].

Write at least a sentence for each function.

A paragraph or more for each module or group of functions.

At least a paragraph for the program itself.

In these, explain what the code is supposed to do .

Add a comment after every few lines of code stating what those lines are intended to do , put these in every time you move to a new step of the algorithm.

How does it work ?

This is less important than "what does it do?", it's often possible to answer this one by reading the code -- but only if the code isn't buggy.

If you have a loop counting from 1 to 20, I can't tell if you're accidentally or deliberately ignoring element zero. The only way I can know for sure is if you commented the code.

Any code where you can expect an error should have a comment stating your intention.

Anywhere that uses pointers.

Anywhere that you have complicated logic.

regular expressions, or elegant code that another person might not understand.

Why was it written this way?

Why

Why a stack, not a list?

Why in C not in Python?

Why for not while?

Record your choices, and record the reasons for them. Later maintainers (or you!) can then make informed decisions about updating and modifying the code. Circumstances change, and people forget why decisions were made the way they were.

The only certain way to remember your reasons is to document them.

Why was it written this way?

Also record bug fixes.

Later on, someone will (not might!) be tempted to pull out an apparently useless bit of code that you put in to prevent [baz] problems in [quux] machines. And it took you a week to get it right.

Which part does what?

Back to our fooed bar. We have determined that fooing is, in fact, a feature of our program, and that the bug reporter is correct and fooing is failing. How do we fix it? Where do we find the foo module?

The most effective way from the maintainer's point of view is to have some sort of document with the source code which describes the overall structure of the code and explains which code modules support which user-view features.

Ex:

This doesn't have to be a long document, and can be a simple list like:

foo

foo.c, interface.c

baz

baz.c, quux.h, interface.c

Where do I find each part?

You've been thorough documenting your code, and carefully written an index of features and modules. Your maintainer knows he's after foo.c. So where is it?

If your feature index lists functions rather than files, you will need to list which file each function is in. You can list the functions as "foo() in foo.c" in the feature index.

Who wrote it?

For all above or for any reasons -- someone might need to ask you about the code.

When was it written?

Add this, too.

It might be useful to the supervisor -- and it also gives a guideline for what sort of machine you wrote it for.

Prog. Documentation

Javadoc tools generating API documentation in HTML format from doc comments in source code.

The C# compiler providing documentation comments in your code to an XML file.

Format of JAVA Doc Comment

A doc comment must precede a class, field, constructor or method declaration. a description followed by block tags.

The special comments in the source code that are delimited by the /** ... */ delimiters.

@param (classes, interfaces, methods and constructors only)

@return (methods only)

@exception

@author (classes and interfaces only, required)

@version (classes and interfaces only, required)

@see

@since

@param

The @param tag is followed by the name of the parameter, followed by a description of the parameter.

Parameter names are lowercase by convention.

* @param url an absolute URL giving the base location of the

* image

* @param name the location of the image, relative to the url

* argument

* @param x the x-coordinate, measured in pixels

#Note

The PHP @param tag followed first by the data type then the name

@return

Having an explicit @return tag makes it easier for someone to find the return value quickly.

@throws ( @exception )

A @throws tag should be included for any checked exceptions (declared in the throws clause).

Example:

/**

* @throws IOException If an input or output

* exception occurred

*/

@author

You can provide one @author tag, multiple @author tags, or no @author tags.

Example:

* @author Bassem Zaitoun

* @author Mohammed Bassem Zaitoun

@version, @since

Version and since are optional tags used if the project have many versions or the class or method used in different programs.

Example:

@version 1.5

@since 1.5

@see

Adds a "See Also" heading with a link or text entry that points to reference .

A doc comment may contain any number of @see tags, which are all grouped under the same heading.

@see tag has three variations ( string , URL , package label ).

@see "The Java Programming Language“.

@see <a href=" URL # value "> label </a>

@see # method(Type argname, Type argname,...)

@see package.Class # method(Type argname, Type argname,...)

Format of .NET XML Doc

The <c> tag gives you a way to indicate that text within a description should be marked as code.

The <code> tag gives you a way to indicate multiple lines as code.

The <example> tag lets you specify an example of how to use a method or other library member.

The <exception> tag lets you specify which exceptions can be thrown.

The <include> tag lets you refer to comments in another file that describe the types and members in your source code.

The <listheader> block is used to define the heading row of either a table or definition list.

The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method.

The <permission> tag lets you document the access of a member.

The <see> tag lets you specify a link from within text.

The <seealso> tag lets you specify the text that you might want to appear in a See Also section.

The <summary> tag should be used to describe classes, methods and constructors.

Use <remarks> to add supplemental information to a type description.

The <value> tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

Reference