minaa-chan

So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.

That other mechanism is comments.

I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true.

Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.

That just makes two things that need to be commented doesn't it?

When I read code I care about what the code is supposed to do and why it's supposed to do that.

There is code that passes the current tests and is logically sound but no longer fits the business requirements. Knowing that it was implemented to solve a certain use case helps the reader / reviewer see whether the code and the test still fit or if they should be updated.

The best comments I've come across comment the intention and any context that isn't immediately obvious from the function.

I don't. I do "good" things because that's the way I was raised. I actually dislike getting thanked or anything that draws attention to the "good" thing I did because it seems so needless.

Occasionally I'll feel a twinge of guilt if I could've helped out and didn't but usually I do it out of habit.