8 ms·

I have no idea why that isn't standard practice in every codebase. I should be able to figure out your code without having to ask, or dig through issues or comm

I have no idea why that isn't standard practice in every codebase. I should be able to figure out your code without having to ask, or dig through issues or commit messages. Just tell me what it's for!

SoylentOrange 3y ago
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__ 3y ago
  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 3y ago
  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 3y ago
  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 3y ago
    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 3y ago
      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 3y ago
        Did you update the comment? :-)
        withinboredom 3y ago
        // there are two kinds of mutually exclusive commentors enum kinds { writers; readers; updaters; }
ComputerGuru 3y ago
It kind of is in rust now, with module-level documentation given its own specific AST representation instead of just being a comment at the top of the file (a file is a module).
nologic01 3y ago
the average programmer thinks they are writting significantly above average clean code, so no need to document it :-)

SoylentOrange 3y ago

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__ 3y ago
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 3y ago
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 3y ago
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 3y ago
  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 3y ago
    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 3y ago
      Did you update the comment? :-)
      - withinboredom 3y ago
        // there are two kinds of mutually exclusive commentors enum kinds { writers; readers; updaters; }

ComputerGuru 3y ago

It kind of is in rust now, with module-level documentation given its own specific AST representation instead of just being a comment at the top of the file (a file is a module).

nologic01 3y ago

the average programmer thinks they are writting significantly above average clean code, so no need to document it :-)