This is the same as human languages
Posted Nov 4, 2011 22:37 UTC (Fri) by khim
In reply to: Flippant code comments
Parent article: Quote of the week
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?
to post comments)