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.
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();
I'm also at least slightly troubled by the assertion (not made Aschwin, but others) that the code is the only artifact worth reviewing. If you have a specification, or documentation, that doesn't line up with the product, why do you have those documents in the first place? Again, I don't expect that those documents will outline the specific implementation (though, if your shop uses software design documents, they should), but I should be able to get a reasonable explanation of how the system works from the docs. If this isn't the case, how do you expect to have someone test the system?
All that said, I agree that having the ability to read and understand others' code is critical to being a good programmer.