It's a learned skill, and perhaps even more fundamental than simply writing. In fact, simply reading is not enough. You have to read critically for correctness. How else would you know that the comments no longer describe what the code is doing? One supposes this lack contributes more bugs than even Microsoft's evil aura and intents.
I like assembly too. My comment/code ratio is about 3:1, and I include the occasional soliloquy, math derivation, protocol description, and ascii-art diagram. I saw some Windows source code a while back: a simple API wound up being a score of source files, many doing nothing but passing stuff off to others under assumed names. Each did have the Microsoft-mandatory comment header. Under "Description of function:" people had filled in useful things like "what it says."
John
I guess that's why I prefer assmebler, PL/I, or VHDL. Assembler forces comments to be able to figure out what you did next week. The others are verbose enough to get by with fewer comments (a high-level diagram would be nice). C/C++ are unreadable, IMO.
A former manager (a DOS/MVS developer in a former life) had the term "xenocryptophobia" on a plague above his desk. I thought it appropriate. It rubbed off.
-- Keith
message
adesign
I do the same. The low-level drivers have ASCII art register definitions in the headers and a long description of exactly what the module is supposed to do, with all parameters and returns specified. I also use running comments to describe the results of each step and where it's all heading.
Why am I not surprised. "If it was hard to write it _should_ be hard to understand."
-- Keith
On Sun, 25 Dec 2005 10:33:54 -0500, Keith Williams wrote: ...
But, but, but - - I don't know yet, what I did next week! )-;
Thanks, Rich
Just out of curiosity, I just now went and took a look at the Linux kernel source.
What a freakin' nightmare!
Thanks! Rich
You don't? I do, it's all scheduled. Next week I went back to work. ;-)
Let me try again; "...forces comments to be able to figure out what you did, the next week."
-- Keith
P.S. Touchy, touchy
ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.