Documenting source code

http://erik-poupaert.blogspot.com/2012/12/documenting-source-code.html

by eriksank • 14 years ago

1 3 14 years ago

erik-poupaert.blogspot.com

watt2• 14 years ago

Well, well. If your "undocumentation" is in form of

    /** nTuple class */
    class nTuple {
    ...

... or

    /** creates copy of nTuple */
    static function copy($nTuple)
    ...

... or

    /**  Creates a string representation of an n-tuple. */
    static function toString($nTuple)

no wonder you will not be seeing the value of documenting. (Hint: just leave such trivial comments out. In case of "copy" function, you might want to tell us why would one need to create a copy, or why it's important. Or probably it's so obvious you should not bother at all!)

Document what's surprising. Document "why" instead of "what". And don't just repeat yourself in comments.

eriksank• 14 years ago

The documentation standards seem to be insisting on that kind of things. The "why" can only be clarified in the location where it is used; which I did: Changing an array value, changes the original object, while the creation of countering n-tuples requires the creation of new objects mostly equal to the original object.

watt2• 14 years ago

If you say that documentation standards are mostly bullshit, I will agree completely. It follows that documentation produced following the standard will also be mostly bullshit. However this does not mean that documentation in general is useless. At this point in time, you just have to use your head, use your own common sense...

Documenting source code

Related Stories