Flippant code comments

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

I'm not a kernel hacker, and I am a native English speaker, but yeah, I do prefer reading code to reading English descriptions of that code. Comments are useful when they explain things like invariants being maintained or what code that isn't on the screen is doing that will interact with the code that I'm looking at, but otherwise, eh. Code fluency is a skill you can acquire. I'm pretty sure there are people around here who do things like read random source code for entertainment.

I have a pet theory, totally unsupported by evidence, that this is part of the famous "open source quality advantage". FOSS hackers spend more time reading code (why *not* run a quick apt-get source to satisfy a passing curiosity?), so of course they're better at reading it. And not only does this have obvious advantages in terms of debugging and maintenance programming, it means you're more likely to notice bugs on a casual read-through, you can more quickly skim through a source file to remind yourself how it all fits together, you can hold more of a complicated program's structure in your head at once, and quickly look up some detail you need to know without having to swap out the other stuff you're thinking about. At least, that's my experience.

I find it very strange that CS programs emphasize writing code. Skill at reading code is much harder to acquire, and more valuable.

Maybe this should have gone into the "why the death of google codesearch is sad" thread...

Flippant code comments

Posted Nov 4, 2011 21:53 UTC (Fri) by giraffedata (guest, #1954) [Link] (6 responses)

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.

Flippant code comments

Posted Nov 4, 2011 22:16 UTC (Fri) by njs (subscriber, #40338) [Link]

Fair enough. And obviously code varies vastly in readability, just like prose does. My impression is that the kernel values code readability much more highly than mplayer does.

This is the same as human languages

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

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 (guest, #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 19:21 UTC (Sat) by Baylink (guest, #755) [Link] (1 responses)

Hey! An Mplayer hacker.

Any thoughts on this?

http://markplusplus.wordpress.com/2006/10/01/pitch-correc...

OT: MPlayer

Posted Nov 12, 2011 22:41 UTC (Sat) by giraffedata (guest, #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.

Flippant code comments

Posted Nov 9, 2011 13:07 UTC (Wed) by nix (subscriber, #2304) [Link]

Oh, I've got code fluency. It's just that giant lumps of source code with not a single comment are rather... straining. At least the kernel has decent names for its structure members :)