5 ms·

But comments go out of date, and the compiler doesn’t check them against the implementation. To document + enforce the intended functionality, use tests.

by dskrvk 2y ago

runevault 2y ago
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. https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html https://doc.rust-lang.org/rustdoc/write-documentation/docume...
- rob74 2y ago
  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 https://go.dev/blog/examples)
  - runevault 2y ago
    Interesting. I don't know when that was implemented in Rust but clearly Go has had it for a long time, since that post is dated 2015. While things like syntax are important, languages adding tooling like this (along with stuff like package managers) is so important to the continued evolution of the craft of software development.
dijksterhuis 2y ago
tests -> verify intended functionality implementation (the how is right). 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.
- jgwil2 2y ago
  > 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.
  - dijksterhuis 2y ago
    > humans make mistakes All software is built by humans in some way. All software has mistakes. Perfection is an impossible goal.
    - jgwil2 2y ago
      Yeah but there's a fundamental difference between something like tests that can be checked automatically and comments, that have to be checked manually. Because of this, it can be assumed that comments will eventually go out of date.
      - dijksterhuis 2y ago
        Good PR review from a skilled and more senior developer catches these things, most of the time. Just like how tests catch functionality issues , most of the time — bugs still exist in tested software, because people make incorrect assumptions about how/what to test, or implement the test wrong. > it can be assumed that comments will eventually go out of date. Don’t make assumptions. That’s just a lazy excuse for not trying. The same thing could be said for tests > it can be assumed that tests will eventually go out of date So why should we bother updating tests? They’re just going to go out of date?!! Because it makes the codebase easier to work with for someone brand new. Same as comments. Pay down the debt for the next person. The next person could even be you in a year’s time after working in a completely different project for 9 months.
      - consteval 2y ago
        Tests only test functionality, they don't test business context. Comments explain business context. For example, "we have this conditional here because Business needs this requirement (...) satisfied for this customer" Your comment can test the logic works correctly. But someone coming in, without the comment, will say "why are we doing this? Is this a bug or intentional? Is the test bugged, too?" Now, they'll see it's intentional and understand what constraints the code was written under. Your test can't send a slack message to a business analyst and ask them if your understanding is correct. The original dev does that, and then leaves a comment explaining the "why".
marcus_holmes 2y ago
Comments (should) explain the "why" not the "what". The "why" doesn't go out of date, even if the "what" does.
- jjnoakes 2y ago
  The why can also go out of date. Maybe not as frequently? I don't have a great intuition for the ratio, but it is certainly more often than never.
  - marcus_holmes 2y ago
    I dunno, the "why" for me is "why are we doing this, and doing it this way?". If that changes, but somehow the comment isn't changed, that would feel really strange. It's not just tweaking a few lines, it's rewriting the whole routine. If all the code changed but not the comment, that would have to be deliberate, and definitely picked up in code review. Though, obviously, accidents happen, etc. But then that also happens with tests and everything else. I have definitely seen out-of-date tests in code bases, where the test is no longer relevant but still maintained.
    - knappe 2y ago
      So I actually find this helpful because if the why doesn't match the what (code), I know to look back at the history of changes and see why there is a mismatch. This is honestly a great signal that something might have gone sideways in the past while I'm trying to triage a bug or whatever. So even if the comments are out of date, they're still helpful, because I know to go look at why they're out of sync.
      - marcus_holmes 2y ago
        really good point, and well worth mentioning in the "code should be self-documenting and comments are unnecessary" debate.
- kmoser 2y ago
Ferret7446 2y ago
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.
mook 2y ago
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. Pretty sure I'm guilty of that pretty often.
- irthomasthomas 2y ago
  Looking at someone else's code, how would you know which was out of date, the code or the comment?
  - Vegenoid 2y ago
    git blame will show when lines in a file were last changed, and the commit that changed them
  - mook 2y ago
    Does it matter? If the comment doesn't match the code, there's a bug (in the comment or the code). Either way you need to spend time to understand the context and figure out the correct thing, not trusting either.
  - mumblemumble 2y ago
    Looking at the commit history is a great start. Especially if your team actually empowers people to reject code reviews when the commit messages are unclear or insufficiently detailed.
worik 2y ago
> 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

But comments go out of date, and the compiler doesn’t check them against the implementation. To document + enforce the intended functionality, use tests.

by dskrvk 2y ago

But comments go out of date, and the compiler doesn’t check them against the implementation. To document + enforce the intended functionality, use tests.

runevault 2y ago

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. https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html https://doc.rust-lang.org/rustdoc/write-documentation/docume...

rob74 2y ago
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 https://go.dev/blog/examples)
- runevault 2y ago
  Interesting. I don't know when that was implemented in Rust but clearly Go has had it for a long time, since that post is dated 2015. While things like syntax are important, languages adding tooling like this (along with stuff like package managers) is so important to the continued evolution of the craft of software development.

dijksterhuis 2y ago

tests -> verify intended functionality implementation (the how is right). 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.

jgwil2 2y ago
> 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.
- dijksterhuis 2y ago
  > humans make mistakes All software is built by humans in some way. All software has mistakes. Perfection is an impossible goal.
  - jgwil2 2y ago
    Yeah but there's a fundamental difference between something like tests that can be checked automatically and comments, that have to be checked manually. Because of this, it can be assumed that comments will eventually go out of date.
    - dijksterhuis 2y ago
      Good PR review from a skilled and more senior developer catches these things, most of the time. Just like how tests catch functionality issues , most of the time — bugs still exist in tested software, because people make incorrect assumptions about how/what to test, or implement the test wrong. > it can be assumed that comments will eventually go out of date. Don’t make assumptions. That’s just a lazy excuse for not trying. The same thing could be said for tests > it can be assumed that tests will eventually go out of date So why should we bother updating tests? They’re just going to go out of date?!! Because it makes the codebase easier to work with for someone brand new. Same as comments. Pay down the debt for the next person. The next person could even be you in a year’s time after working in a completely different project for 9 months.
    - consteval 2y ago
      Tests only test functionality, they don't test business context. Comments explain business context. For example, "we have this conditional here because Business needs this requirement (...) satisfied for this customer" Your comment can test the logic works correctly. But someone coming in, without the comment, will say "why are we doing this? Is this a bug or intentional? Is the test bugged, too?" Now, they'll see it's intentional and understand what constraints the code was written under. Your test can't send a slack message to a business analyst and ask them if your understanding is correct. The original dev does that, and then leaves a comment explaining the "why".

marcus_holmes 2y ago

Comments (should) explain the "why" not the "what". The "why" doesn't go out of date, even if the "what" does.

jjnoakes 2y ago
The why can also go out of date. Maybe not as frequently? I don't have a great intuition for the ratio, but it is certainly more often than never.
- marcus_holmes 2y ago
  I dunno, the "why" for me is "why are we doing this, and doing it this way?". If that changes, but somehow the comment isn't changed, that would feel really strange. It's not just tweaking a few lines, it's rewriting the whole routine. If all the code changed but not the comment, that would have to be deliberate, and definitely picked up in code review. Though, obviously, accidents happen, etc. But then that also happens with tests and everything else. I have definitely seen out-of-date tests in code bases, where the test is no longer relevant but still maintained.
  - knappe 2y ago
    So I actually find this helpful because if the why doesn't match the what (code), I know to look back at the history of changes and see why there is a mismatch. This is honestly a great signal that something might have gone sideways in the past while I'm trying to triage a bug or whatever. So even if the comments are out of date, they're still helpful, because I know to go look at why they're out of sync.
    - marcus_holmes 2y ago
      really good point, and well worth mentioning in the "code should be self-documenting and comments are unnecessary" debate.
kmoser 2y ago

Ferret7446 2y ago

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.

mook 2y ago

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. Pretty sure I'm guilty of that pretty often.

irthomasthomas 2y ago
Looking at someone else's code, how would you know which was out of date, the code or the comment?
- Vegenoid 2y ago
  git blame will show when lines in a file were last changed, and the commit that changed them
- mook 2y ago
  Does it matter? If the comment doesn't match the code, there's a bug (in the comment or the code). Either way you need to spend time to understand the context and figure out the correct thing, not trusting either.
- mumblemumble 2y ago
  Looking at the commit history is a great start. Especially if your team actually empowers people to reject code reviews when the commit messages are unclear or insufficiently detailed.

worik 2y ago

> 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