Flippant code comments [LWN.net]

Flippant code comments

Posted Nov 4, 2011 21:53 UTC (Fri) by giraffedata (subscriber, #1954)
In reply to: Flippant code comments by njs
Parent article: Quote of the week

Code fluency is a skill you can acquire.

I'm pretty sure I can't. I've read millions of lines of C code written by hundreds of coders. I know the syntax like the back of my hand and I know all the paradigms. I still read English descriptions of computation about 10 times faster than the C implementation. When I have to understand uncommented C code, I usually decipher it little by little and write down my findings in English and then use that document for all my work. For example, I have 1300 lines of English about what various parts of Mplayer do. It saves me hours every few years when I have to fix a bug or add a feature. If I didn't want to preserve the ability to merge Mplayer updates from others, I'd just put that text into the source files as comments.

And that was my point. Brains work differently. Some people criticize others as lazy for not commenting code, but it may be that the others just don't benefit from comments.

(Log in to post comments)

This is the same as human languages

Posted Nov 4, 2011 22:37 UTC (Fri) by khim (subscriber, #9252) [Link]

When I have to understand uncommented C code, I usually decipher it little by little and write down my findings in English and then use that document for all my work.

You are doing it wrong(tm)! Side question: how many human languages do you know? I found that "computer languages" and "human languages" share more then just the second word. The same principles work in both cases. As long as you try to use "first translate the sentence, then understand it" approach you'll be crippled WRT human languages. If you use "decipher it little by little ... and then use that document" approach for computer language you'll be crippled WRT computer languages. You can not learn the skill for one simple reason: you are too busy making sure you'll never even try.

For example, I have 1300 lines of English about what various parts of Mplayer do. It saves me hours every few years when I have to fix a bug or add a feature.

Hmm... This looks like an abstract. Useful thing to have both for large native language creations (like series of novels) and for large programs, too. Does not have anything to do with the ability to read C code.

If I didn't want to preserve the ability to merge Mplayer updates from others, I'd just put that text into the source files as comments.

Why would you want to do that? There are about 600'000 lines of code in Mplayer. Your abstract only includes 1300 lines. Basically only few lines per file. This is useful thing to have - but why will you need to disperse all this succinct knowledge in large mass of highly detailed C code?

This is the same as human languages

Posted Nov 5, 2011 0:16 UTC (Sat) by giraffedata (subscriber, #1954) [Link]

I found that "computer languages" and "human languages" share more then just the second word. The same principles work in both cases.

I agree. But the weakest human language outstrips the most powerful computer language in one area: the ability to express abstraction (and for an obvious reason - it would not survive the concomitant imprecision). And here, we're not talking about computer languages in general, but a particularly low level one: C.

As long as you try to use "first translate the sentence, then understand it" ...

Agreed, and let me be clear on my process: I don't translate each line of C into a line of English. That would be ridiculous (though it is a popular style, especially among assembly language programmers). I translate maybe 50 lines of code into a few sentences. It's that abstraction that many C programmers appear to eschew. They can read the 50 precise lines more easily than the few abstract sentences.

Why would you want to do that? There are about 600'000 lines of code in Mplayer. Your abstract only includes 1300 lines. Basically only few lines per file. This is useful thing to have - but why will you need to disperse all this succinct knowledge in large mass of highly detailed C code?

I've never looked at most of those 600,000 lines. My 1300 lines covers a small fraction of them, and if I were to put them into the code as comments, they would show up as e.g. 20 lines at the top of a 300 line subroutine telling what it does or 10 lines below a variable declaration telling what its value means. Maybe 5 paragraphs at the top of the cache subsystem file explaining what the cache subsystem is and how it works. Since I do have to read some of the individual lines of code, it's easiest to have the English adjacent to them to this degree.

Flippant code comments

Posted Nov 7, 2011 11:47 UTC (Mon) by jezuch (subscriber, #52988) [Link]

Well, I still prefer to read code than the natlang descriptions (which I don't do any of, because they're horribly redundant, except an occasional long comment (which usually gets out of sync with the code fairly quickly)), but reading and trying to understand a piece of *imperative* code is a massive pain for me. Functional and declarative style is so much better for my brain...

OT: MPlayer

Posted Nov 12, 2011 22:41 UTC (Sat) by giraffedata (subscriber, #1954) [Link]

That isn't an area I've worked in.

I've mainly worked on fixing bugs in DVD and audio CD playing, enhancing status display and command interfaces, and adding the ability to display closed captions and program information in captured television.

I use Mplayer in a TV recorder I built myself. And CD and DVD player if I can ever get those to work.