

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

======
watt
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
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.

~~~
watt
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...

