Re: Sometimes, old principles might still be good [OT]

Reiner Karlsberg <karlsberg_at_softart-ge.com> writes:

[...]

> This rule of "Egoless Programming" contained several aspects. Some of these were
> - Use a lot of comments.

"Lots of comments" don't usually do any good. It makes some sense to
document public interfaces but even this only in fairly 'controlled'
circumstances. Otherwise, J. Random Junior Programmer will just copy
and paste the code en bloc, change some or all parts of the code but
not touch the comments at all ("This line already had a comment
attached. Why reinvent it!"). But generally, out-of-line documentation
is better because it can be as comprehensive as desired without
impacting the readability of the code itself. Most inline comments
fall into one of the following three categories:

        - "I don't know what I'm doing myself", generally the result
          of a coding style where people start with "documenting their
          intention" in form of a comment and then try to find a way
          to program that

        - complaints about technical deficiencies of other parts of
          the code ("Doing X would be the right thing here but since
          ... does ..., we can only ...)

        - witticisms aka "fuck me gently with a chainsaw"

and while they all make for more-or-less entertaining reading and
provide some reassuring 'social grooming', they're all useless. In
case of heavily commented code 'falling' onto me (say, because the guy
who f*cked it up has chosen to seek a greener pasture elsewhere), I
usually start with deleting all comments -- after all, if the original
offender had known what he was doing, the thing should be working, and
his erratic musings about what he believed the code should or would do
are not usually very useful, especially considering that the only way
to verify that they're correct is to compare them with the code.

NB: This is totally off topic here and I'm only replying to it because
I posted a fairly "comment free", medium-sized chunk of code here
yesterday. Please consider e-mailling me in case the topic is of
interest to you beyond its "functional usefulness" (eg, winning an
argument without arguments in favour of one's own position, assuming
this position is actually sufficiently stable that arguments in favor
of it could be made, as opposed to 'shifting to whatever location
seems most convenient ATM'. I can't promise that I'll find the time to
reply anytime soon, however).
Received on Tue Jan 29 2013 - 12:09:02 MST