I think there is quite a difference between documentation per se and (inline) code comments. In particular, (inline) code comments are intended to supplement the actual code and to spell out things that are not readily apparent even if identifiers are appropriately chosen, like the intent of a particular fragment, exploitation of obscure language/runtime features or confluence of certain events (like the fact that testing for EMPTY(SomeField) trivially covers EOF), or why some piece of code was mutilated during maintenance. I.e. things that are non-obvious but relevant.
The value of such commentary greatly depends on it being present where it is needed and absent anywhere else. Also, comments must be maintained just as the executable code lest they become worthless and misleading; the chance of comments getting out of sync with the code during maintenance is directly proportional to their degree of redundancy. With the monstrous function headers suggested elsewhere in this thread you'd be lucky if they bore some semblance to reality even during initial coding, much less during maintencance. Not to mention relevance ...
As regards change headers, we use basically the same one-liner scheme as the one posted by Tracy Holzer (except that we use proper YMD format for the date *g*).
Précédent
Suivant
Répondre
Voir le fil de ce thread
Voir le fil de ce thread à partir de ce message seulement
Voir tous les messages de ce thread
Voir tous les messages de ce thread à partir de ce message seulement