But comments go out of date, and the compiler doesn’t check them against the implementation. To document + enforce the intended functionality, use tests.
Outdated context is miles better than no context in my experience. As long as the comment isn't intentionally misleading, it always helps a ton in piecing together what happened, even if the comment is factually wrong when it was written, because I can tell how the original author was mistaken and why it led to the current code.
Outdated comments are great, because it means you probably have a bug right there. If the comment didn't get updated, the code change probably didn't look at all the context and missed things.
Generalizations like that are theoretical, and don't always align with reality. There's nothing wrong with comments summarizing the "what", and in fact doing so is a good thing because it can describe anything from the intention of the code to the business logic. "This function merges array X with array Y, converting all the keys to lowercase because they will be used later by foo()."
The "why" can go out of date, e.g. "do X before Y because [specific thing in Y] is dependent on [specific thing in X]". If you rewrite Y to no longer be dependent on X, the comment is now out of date.
The reality is that any comment can go out of date at any time if the code it describes changes enough. But that's really no excuse for failure to maintain comments. Sure, in reality code is messy and inconsistently written, not even counting comments. Comments are an essential parts of your codebase, and while they are used exclusively by humans, that doesn't mean they are any less worthy of being updated and cultivated.
Comments go out of date because of bad developers.
The same people who do the bare minimum for tests not to explode. But won’t add a new test case for the new branches they just introduced.
The same people who will mangle the code base introducing bizarre dependencies or copy paste the same piece of code rather than refactor.
People who fail to handle errors correctly. My favorite: by wrapping code in a if statement without an else. (else? Get a weird error without logs! Miles away from the call site!)
People who don’t validate inputs.
People who don’t give a monkey about adding context to errors making the thing impossible to debug in prod when they explode.
People who are too lazy or in incompetent to do their job properly and will always jump at the opportunity to save 5 minutes now but waste 5 hours of everybody else’s time later. Because of course these people can’t fix their own bugs!
And of course these are the people who make comments go out of date. I’ve seen them implement a thing literally the line below a TODO or FIXME comment and not delete the line.
Comments going out of date is a shit excuse for not writing comments as far as I’m concerned.
The fact that some people are incompetent should not drive engineering decisions. You should always assume a minimal level of competency.
> Just like updating the tests when code is changed, update the comment when the code is changed.
Well, yeah. But the point is that tests can be run in a pipeline that can fail if the tests fail. Comments going out of date has to get caught by a human, and humans make mistakes.
> To document + enforce the intended functionality, use tests.
Tests go out of date
Tests increase the maintainince burden
The compiler does not ensure code is tested
Tests get duplicated
Mēh! Tests matter, and testing is very important. Good judgment is required
Just like comments.
Writing code requires professional care at every step. The compiler helps of course see, but being professional is more than writing code that compiles
It involves documents too. And tests. Not too many (tests or documents) but not too few
Undocumented code is an enormous burden to maintain (I am eyebrows deep in such a project now). It is not enough to just write code and tests, documents including inline comments, are crucial
Note in Rust if you include comments with code that will run as tests but be inline in your main code instead of having to find the relevant test function to confirm functionality.
Go has something similar: functions marked as examples that are both run as tests and shown and run as examples in the documentation (https://go.dev/blog/examples)
Ferret7446|1 year ago
mook|1 year ago
Pretty sure I'm guilty of that pretty often.
irthomasthomas|1 year ago
marcus_holmes|1 year ago
kmoser|1 year ago
The "why" can go out of date, e.g. "do X before Y because [specific thing in Y] is dependent on [specific thing in X]". If you rewrite Y to no longer be dependent on X, the comment is now out of date.
The reality is that any comment can go out of date at any time if the code it describes changes enough. But that's really no excuse for failure to maintain comments. Sure, in reality code is messy and inconsistently written, not even counting comments. Comments are an essential parts of your codebase, and while they are used exclusively by humans, that doesn't mean they are any less worthy of being updated and cultivated.
jjnoakes|1 year ago
dijksterhuis|1 year ago
comments -> why intended functionality was implemented that specific way (marketing wanted X because of Y, so we had to do it like Z with a bit of A).
> But comments go out of date
Just like updating the tests when code is changed, update the comment when the code is changed.
jackjeff|1 year ago
The same people who do the bare minimum for tests not to explode. But won’t add a new test case for the new branches they just introduced.
The same people who will mangle the code base introducing bizarre dependencies or copy paste the same piece of code rather than refactor.
People who fail to handle errors correctly. My favorite: by wrapping code in a if statement without an else. (else? Get a weird error without logs! Miles away from the call site!)
People who don’t validate inputs.
People who don’t give a monkey about adding context to errors making the thing impossible to debug in prod when they explode.
People who are too lazy or in incompetent to do their job properly and will always jump at the opportunity to save 5 minutes now but waste 5 hours of everybody else’s time later. Because of course these people can’t fix their own bugs!
And of course these are the people who make comments go out of date. I’ve seen them implement a thing literally the line below a TODO or FIXME comment and not delete the line.
Comments going out of date is a shit excuse for not writing comments as far as I’m concerned.
The fact that some people are incompetent should not drive engineering decisions. You should always assume a minimal level of competency.
jgwil2|1 year ago
Well, yeah. But the point is that tests can be run in a pipeline that can fail if the tests fail. Comments going out of date has to get caught by a human, and humans make mistakes.
worik|1 year ago
Tests go out of date
Tests increase the maintainince burden
The compiler does not ensure code is tested
Tests get duplicated
Mēh! Tests matter, and testing is very important. Good judgment is required
Just like comments.
Writing code requires professional care at every step. The compiler helps of course see, but being professional is more than writing code that compiles
It involves documents too. And tests. Not too many (tests or documents) but not too few
Undocumented code is an enormous burden to maintain (I am eyebrows deep in such a project now). It is not enough to just write code and tests, documents including inline comments, are crucial
runevault|1 year ago
https://doc.rust-lang.org/rustdoc/write-documentation/docume...
rob74|1 year ago