4 ms·

I'm having trouble wrapping my head around this--it seems to boil down to "I don't use comments because then I'd have to actually maintain them." I certainly d

by bmj 17y ago

I'm having trouble wrapping my head around this--it seems to boil down to "I don't use comments because then I'd have to actually maintain them." I certainly don't think that every line of code should be commented, but as others have pointed out, some comments are important, particularly around why, say, an algorithm was implemented. Even for my own code, I need these little reminders, especially when I'm jumping between projects frequently. 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.

JoeAltmaier 17y ago
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.
- bmj 17y ago
  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 always intend on cleaning these up, but often never do.

by bmj 17y ago

JoeAltmaier 17y ago

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.

bmj 17y ago
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 always intend on cleaning these up, but often never do.