4 ms·

I don't understand how they are hard to find. It's trivial to find where the file was moved from. What I truly care about is why something is the way it is, wh

I don't understand how they are hard to find. It's trivial to find where the file was moved from. What I truly care about is why something is the way it is, what is the rationale behind it, how it works with other parts of the codebase, what problems it solves, what is tricky about it, what to pay attention to and so on. I don't care at all about the code that was written and an explanation to it because this I can read myself in the code. The best place I've found for this is a code commit because it can tie different parts of the codebase together and add a lot of context to a change. I commit heavily and don't squash. A long comment in a commit that contains all file changes related to a certain feature, bug or whatever adds a lot more information than a comment in one file. When other people do it, it helps me a lot more than chasing their (outdated) code comments throughout the codebase. But if that doesn't work for you, then don't do it. Just don't be dogmatic and dismissive. I accept there might be situations and codebases where this doesn't work.

cerved 5y ago
Lot's of IDEs and external tools do very basic git integration ¯\_(ツ)_/¯ I think JetBrains is probably the best of the IDEs
fenomas 5y ago
I'm lost. Are you talking about meta-level comments, like "here's why this change is being made", that aren't directly tied to any particular line of code? If so, certainly putting that stuff in commits makes sense. But for regular "explanatory note about this variable/function/etc" comments, how does one work if those things are in commit logs? If you're reading code and something is unclear, do you look back through the commit messages of every commit that's ever touched that line, just in case one of them has something relevant?
- treis 5y ago
  IDEs can show commit history. But you're right that it can get messy tracing back to the original commit when a file has been changed many times. But for the most part I feel like comments should be automated tests. If a line is there for an edge case it should have a matching test for that edge case. The only exceptions I see are for performance optimizations or some other situation where you can't easily test.
  - fenomas 5y ago
    > IDEs can show commit history. How you check the commit history is beside the point - the question is, do you read the entire commit log history for a chunk of code before editing it? If not, any comments there might as well not exist - functionally speaking you're maintaining an uncommented codebase.
  - codedokode 5y ago
    Tests are not a replacement for comments or documentation. Tests check that A() returns x but don't explain what is A, x and why it should return it.
    - treis 5y ago
      That goes in the test name. You'll have something like Feature A "It should return X in [some edge case]" That's where any link to a use case should be.

cerved 5y ago

Lot's of IDEs and external tools do very basic git integration ¯\_(ツ)_/¯ I think JetBrains is probably the best of the IDEs

fenomas 5y ago

I'm lost. Are you talking about meta-level comments, like "here's why this change is being made", that aren't directly tied to any particular line of code? If so, certainly putting that stuff in commits makes sense. But for regular "explanatory note about this variable/function/etc" comments, how does one work if those things are in commit logs? If you're reading code and something is unclear, do you look back through the commit messages of every commit that's ever touched that line, just in case one of them has something relevant?

treis 5y ago
IDEs can show commit history. But you're right that it can get messy tracing back to the original commit when a file has been changed many times. But for the most part I feel like comments should be automated tests. If a line is there for an edge case it should have a matching test for that edge case. The only exceptions I see are for performance optimizations or some other situation where you can't easily test.
- fenomas 5y ago
  > IDEs can show commit history. How you check the commit history is beside the point - the question is, do you read the entire commit log history for a chunk of code before editing it? If not, any comments there might as well not exist - functionally speaking you're maintaining an uncommented codebase.
- codedokode 5y ago
  Tests are not a replacement for comments or documentation. Tests check that A() returns x but don't explain what is A, x and why it should return it.
  - treis 5y ago
    That goes in the test name. You'll have something like Feature A "It should return X in [some edge case]" That's where any link to a use case should be.