[dijksterhuis]

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.

[jackjeff]

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.

[dijksterhuis]

> Comments going out of date is a shit excuse for not writing comments as far as I’m concerned.

I agree.

> Comments go out of date because of bad developers

I disagree.

Comments can also go out of date because

- developer is having a really shit time atm and their head is not in the game (bad looking after people management)

- developer is on a one day a week contract and doesn’t have the time in their contract to write big header comments explaining nuances (bad strategy)

- developer thought it looked obvious to them but it’s not obvious at review time (developer is being classic human)

- developer is getting pushed to deliver the thing now now now (bad workload management)

Most of those are the result of some decision made by someone who was not the developer (they’re all real cases). And they are the “non-code blockers” that good managers solve for us, so we can focus on getting good stuff done.

I’ve been where it seems like you are at. Blaming others for being bad didn’t help me. I had to lower my expectations of others, keeping my expectations for myself. Then get on about teaching willing people how they could be better. Might be making a few assumptions/projecting a bit there, but that’s my experience with “bad developers”.

Being any type of “leader” is lonely. Whether that’s an official role assigned to you or not. Or if it’s just a skill level thing. No one can quite match up to the expectations or understand what we see and why. But explaining it goes a long way with the right ones.

[jgwil2]

> 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]

> humans make mistakes

All software is built by humans in some way. All software has mistakes.

Perfection is an impossible goal.

[jgwil2]

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]

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]

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".