3 ms·

>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient. It's a great

>The idea of writing code for a machine and adding meta-information for humans to better understand the context isn't a bad idea, it's efficient. It's a great idea. One of the best. I think many people will agree with that. But there needs to be an equally effective way to keep the comments up to date. Because in my short experience programming professionally, the insidious part about comments is that as soon as one is shown to be a lie, none of them are reliable anymore. And it's very easy for a comment to become a lie as code evolves. This is why things like unit tests are more attractive as a form of documentation - if the tests lie, the build fails, forcing you to fix lies.

galangalalgol 7y ago
This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.
- ken 7y ago
  I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too. The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.
ken 7y ago
Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation. For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this: /* The principle used to locate the table name in the CREATE TRIGGER ** statement is that the table name is the first token that is immediatedly ** preceded by either TK_ON or TK_DOT and immediatedly followed by one ** of TK_WHEN, TK_BEGIN or TK_FOR. Another great one: ** Note that ON cannot be a database, table or column name, so ** there is no need to worry about syntax like ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc. What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on. I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".
Gibbon1 7y ago
> But there needs to be an equally effective way to keep the comments up to date. Yeah this is called code review. If someone repeatedly submits code with comments that are out of date then their manager needs to have a one on one with them.
tomcatfish 7y ago
Rust's doctests [1] are pretty useful for weaving some comments into the code while also allowing testing on compilation. If they are out of date, just running the test command will alert you that the code and documentation do not match. [1] : https://doc.rust-lang.org/rustdoc/documentation-tests.html https://doc.rust-lang.org/rustdoc/documentation-tests.html

galangalalgol 7y ago

This is my primary problem with comments. I have worked in very large 20year ol code bases both when I have been on the team for most of that time and when I walked in at the end. In both cases almost half the comments are at least partially incorrect.

ken 7y ago
I've worked on large, old codebases before, too, and in my experience half the functions are at least partially incorrect (i.e., have bugs), too. The solution in both cases is the same: when you find problems, fix them. Don't throw out the baby with the bathwater.

ken 7y ago

Maybe I'm reading the wrong programs, but I haven't seen any unit tests that were an adequate replacement for either comments or out-of-band documentation. For example, I looked up the SQLite source (which often comes up here as an example of a well-written program), picked the first source file I saw (alter.c), and one of the first comments is this: /* The principle used to locate the table name in the CREATE TRIGGER ** statement is that the table name is the first token that is immediatedly ** preceded by either TK_ON or TK_DOT and immediatedly followed by one ** of TK_WHEN, TK_BEGIN or TK_FOR. Another great one: ** Note that ON cannot be a database, table or column name, so ** there is no need to worry about syntax like ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc. What unit test would you write to convey this information? Tests can be helpful but they serve a completely different purpose. You can of course write a test to cover the same ground as these comments (and knowing SQLite, they probably did), but a unit test to poke at corner cases is nowhere near as clear as simply stating what's going on. I think the article means to suggest that one possible way to nudge programmers to keep comments up-to-date is to have editors that don't make them appear "washed out".

Gibbon1 7y ago

> But there needs to be an equally effective way to keep the comments up to date. Yeah this is called code review. If someone repeatedly submits code with comments that are out of date then their manager needs to have a one on one with them.

tomcatfish 7y ago

Rust's doctests [1] are pretty useful for weaving some comments into the code while also allowing testing on compilation. If they are out of date, just running the test command will alert you that the code and documentation do not match. [1] : https://doc.rust-lang.org/rustdoc/documentation-tests.html https://doc.rust-lang.org/rustdoc/documentation-tests.html