[SoylentOrange]

Because it takes a lot of time and because the comments can get outdated. I also want this for all my code bases. But do I always do this myself? No, especially on green field projects. I will sometimes go back and annotate them later.

[mhh__]

They can get outdated but they usually don't. It's a good litmus test for if a file is too big / small if it's purpose is hard to nail down.

[akira2501]

Trying to understand what I previously wrote and why I wrote it takes more time than I ever care to spend. I'd much rather have the comments, plus at this point, by making them a "first class" part of my code, I find them much easier to write and I find the narrative style I use incredibly useful in laying out a new structure but also in refactoring old ones.

[withinboredom]

Even outdated comments can tell you the original purpose of the code, which helps if you're looking for a bug. Especially if you're looking for a bug.

If someone didn't take the time to update the comments and the reviewers didn't point it out, then you've probably found the bug because someone was cowboying some shitty code.

[alex_reg]

I have the opposite experience.

Outdated comments are often way worse than no comments, because they can give you wrong ideas that aren't true anymore, and send you off in the wrong direction before you finally figure out the comment was wrong.

[elteto]

Indeed. I recently found this piece of code:

    if (X) assert(false); // we never do X, ever, anywhere.

Then I look over to the other pane, where I have a different, but related file open:

    if (exact same X) { do_useful_stuff(); }

It got a chuckle out of me.

[jgilias]

Did you update the comment? :-)

[withinboredom]

// there are two kinds of mutually exclusive commentors

enum kinds { writers; readers; updaters; }