How to write documentation when programming

Question

Do you have such a habit that when you are coding, you write the documentation as well, and make sure that they are in sync.

How can achieve that? What do you write down? The function logical? The concept? Or other best-practices? Thanks in advance!

Answer 1

I don't, but you can use XML comment syntax to help achieve it somewhat. It will let you document your classes, properties, and method calls at least. Then you can use build automation to construct a CHM file for you. Investigate Sandcastle for this.

Otherwise a wiki that helps track your team collaboration is useful too. Quite often these things turn into "information pools" where people describe something about the system. These can be used to build documentation too.

Finally, release notes can be constructed if you have integration with your tracking store. For example, TFS will let you get all work items and changesets for any given build, which is quite useful for building release notes.

Answer 2

I write the documentation structure before I start and change it while I'm writing. I use Design by Contract as a structure what to write in the documentation:

http://en.wikipedia.org/wiki/Design_by_contract

• Acceptable and unacceptable input values or types, and their meanings
• Return values or types, and their meanings
• Error and exception conditions values or types, that can occur, and their meanings
• Side effects
• Preconditions, which subclasses may weaken (but not strengthen)
• Postconditions, which subclasses may strengthen (but not weaken)
• Invariants, which subclasses may strengthen (but not weaken)
• (more rarely) Performance guarantees, e.g. for time or space used

Answer 3

Those things should be preferably in the design spec (depending on the problem domain) . The rest I like to write in-code with specific tags and then create the documentation automatically. One excellent tool for this is doxygen but there are plenty of others.

This way documentation is done almost automatically as I like to comment my code while I work on it.

Answer 4

It depends on the context of the documentation. If you are documenting it for other developers then I take the view that decent unit tests and variable naming with comments then the code will be self documenting.

In the context of external APIs for customers to use then I normally take the approach of documenting the item when I have finished writing that functionality.

Answer 5

1. Make code as self documenting as possible -
2. Draw pictures simply and easily electronically
3. Grab docs as sound bites not essays - such use an internal blog/wiki etc to grab info with screen shots and thoughts. Mind maps help

This helps me document as I go along.

in essence simple tools to collect ideas and then they're easy to put into bigger docs if needed. Use good tools I use livewriter, mediwiki, snagit, onenote and freemind.

I hate writing docs - so I collect thoughts as I go along.

Answer 6

Well written, well commented code should not really need much extra programmer documentation. As for the end-user documents, I write the help files for my appliocations at the same time as I implement each feature, and the tutorials when I've done most of the coding. However, I've come to think that writing the tutorials earlier in the process would be a better idea.

Answer 7

I am a python programmer and I write a lot of doctests, which is a python module that allows you to write tests as examples of function's usage in the documentation string of every function. Have a look at the example from here:

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    If the result is small enough to fit in an int, return an int.
    Else return a long.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    """

The two last lines are an example of the usage of the function, and can be executed using the doctest module. This way, you accomplish that:

• you put an example of usage of the function, so your users will know how to use it;
• if you include the test in your test suite and run tests often, you will be noticed if the example get broken by a change in the code
• it doesn't take too much time to write these kind of examples.

I usually start with creating stub functions and writing the doctests, to have an idea of how each function will work and which are the expected inputs/outputs; thank to this approach, I always have at least a short documentation of every function and module I write.

From time to time, I write a longer document explaining how my modules can be used (for my colleagues) and I always use the doctest syntax; however, reguarding your question, I never do more than this, sometimes I can write a blog comment on my work or on a library I wrote, but I don't have the time to write longer documentation.