Re:How to Read Other People's Code -- And Why
by JoeAltmaier on Friday October 23, 2009 @09:43AM
(#898712)
Well said. Comments come in classes, with different purposes.
Somewhere (at the top of the module?) its helpful to mention the external dependencies - meta-information that will NOT be found anywhere in the code.
For each code unit (method/function/template) explain why it exists, deficiencies, use case. Again, information not immediately obvious by reading code.
Finally, those strange lines of code with magic numbers, obscure syntax, checks for apparent side-effects need some illumination.
Lastly, and leastly, describing the code itself. These are the comments that get old fastest.
[ Parent
| on HN ]
I would add one more class of comments that would sit at the bottom of the hierarchy: TODOs. When I'm sketching out functions, I typically outline what should be done with within the context of the function, then fill in the implementation details later. This often leads to stuff like this:
// Replace with a link to the core
AddStartupShortcut("Shell.lnk", Path.Combine(INSTALL_PATH, "foo.exe"));
// Update device time:
_log.Information("Updating device time...");
SetDeviceTime();