5 ms·

Having worked with Rails folk for many years, they do have some weird strong opinions, this being one. The argument that comments shouldn't be made because they

Having worked with Rails folk for many years, they do have some weird strong opinions, this being one. The argument that comments shouldn't be made because they'll "become stale" is pretty lame IMO. It's either not a big deal or the end of the fucking world for some reason lol. Maintaining code is just... work. You just do it. That includes comments.

mgkimsal 4y ago
> The argument that comments shouldn't be made because they'll "become stale" is pretty lame IMO Better not write tests either, because those will become stale too. And any sort of user documentation/support/etc. It'll all just become stale. It's almost as if code is just part of a larger 'thing' that has to be maintained.
- tcgv 4y ago
  > Better not write tests either, because those will become stale too Unit tests are easier to maintain when incorporated to a CI/CD pipeline. Then every pushed commit (or Merge Request) will trigger the test suite to run and in case one of the tests fails the team will know.
- p1necone 4y ago
  (well written) tests tend to fail (or fail to compile) if they're 'stale' though, so they force you to maintain them just like other code. (I'm not arguing against writing comments though - the 'they'll get stale' thing is not enough to make them not valuable)
  - hbrn 4y ago
    I don't see a difference. If you write good tests and use a tool (CI) that detects them going stale, tests will never be stale. If you write good comments and use a tool (code review) that detects them going stale, comments will never be stale. In order for tests to not get stale, you need perfect (well written) tests. In order for comments to not get stale, you need perfect code reviews. Neither of those exist in real world: code reviews are done by humans, tests are written by humans.
- randomdata 4y ago
  > Better not write tests either, because those will become stale too. They do go stale, but tests were invented exactly so that your documentation is able to alert you when it has gone stale. Their existence rests on being an attempt to solve to this problem.
- jrumbut 4y ago
  The difference between tests and comments is that comments become stale silently.
  - hbrn 4y ago
    Only under assumption that you are writing perfect tests. But if you are capable of writing perfect tests, why haven't you written perfect software in the first place?
- BurningFrog 4y ago
  When tests go stale the build goes red, and you know to fix things. Comments transition from truth to lie without any indication.
  - vkou 4y ago
    > Comments transition from truth to lie without any indication. Only if you don't do code reviews. The reviewer should be checking for this.
  - still_grokking 4y ago
    Only if you don't maintain your code. Guess what: Comments are part of the code. Like all other documentation!
    - BurningFrog 4y ago
      Snark aside, I think we can agree that there is nothing automatic telling you when a comment is out of date. If you have a strong discipline of manually checking every possibly relevant comment with each review, I can see how that can mostly work (manual human checks are never perfect). I've never seen anything close to that process, so it's hard to know how it would work. It seems to require a lot of discipline and effort.
    - deleted 4y ago
      [deleted]
  - linuxftw 4y ago
    This was true before git blame. Now I can see when the comment was created and the original code it described if I have any doubts about the veracity of the comments.
    - kazinator 4y ago
      If you have git blame, you can see a detailed log messages pertaining to the commits which touch some lines of code. You don't need it to be littered by comments. You seem to think that git invented blame. This appeared in previous version control systems, e.g. "cvs annotate" whose synonym is "cvs blame".
- deleted 4y ago
  [deleted]
- q7xvh97o2pDhNrh 4y ago
  Why stop there? The code will become stale, too. Best to not write any of that either.
- hayst4ck 4y ago
  I don't think your comment tries to paint the best case for the point of view you are opposed to or show an understanding of the philosophy you reject. Tests represent truth in the same way code represents truth. In many ways the tests represent truth more than the code represents truth. Tests state "this is what I want" and then interrogate the code to verify that the code itself does what I want. Tests by definition can not be stale (unless they are never called). The ruby community is where I first learned about test driven development which is philosophically the idea that tests are the highest level of semantic importance. There are DSL's in ruby land for writing tests like you might write comments: https://semaphoreci.com/community/tutorials/getting-started-with-rspec https://semaphoreci.com/community/tutorials/getting-started-... If tests describe what you want, and code describes how it happens, then the major piece left is why it is the way it is, which almost everyone in this thread agrees is the most important thing to comment.
sky_rw 4y ago
Rails developers (myself included) are lazy by design, and thus eschew anything requiring redundant work. Most operate under the principle that "it was hard to write, it should be hard to read"
- TedDoesntTalk 4y ago
  [flagged]
  - the_sleaze9 4y ago
    Personal attacks aren't kosher at Hacker News.
    - TedDoesntTalk 4y ago
      It’s not an attack. It’s an observation based on his lack of team awareness. One of the marks of a senior engineer is someone who is aware he’s part of a group and strives to contribute to a group, rather than a soloist mindset. Call is social maturity if you like.
makeitdouble 4y ago
> Maintaining code is just... work. You just do it. There is an argument about reducing the amount of work. On the staleness of comments, it's a real thing. In particular, on comments explaining design decisions, they will often touch on aspects of the system that are outside of the specific method they are attached to, and nobody will go back to them to rewrite all that prose. We had a project with a ton of documentation written in the first 2 years, and as engineer count grew, these comments just disappeared as again and again they were causing misunderstandings, and actual documentation was already written in the internal wiki as each refactorings and new features were discussed and designed. It's not just a rails thing, and after a while people stop trusting comments altogether, which make updating them a chore more than anything.
- davidw 4y ago
  > actual documentation was already written in the internal wiki I think that's a reasonable approach if it's easy to find the relevant section of the wiki that describes the code you're looking at by searching. Or just have a comment in the code that points to the wiki. The important thing is to document the "why's".

mgkimsal 4y ago

> The argument that comments shouldn't be made because they'll "become stale" is pretty lame IMO Better not write tests either, because those will become stale too. And any sort of user documentation/support/etc. It'll all just become stale. It's almost as if code is just part of a larger 'thing' that has to be maintained.

tcgv 4y ago
> Better not write tests either, because those will become stale too Unit tests are easier to maintain when incorporated to a CI/CD pipeline. Then every pushed commit (or Merge Request) will trigger the test suite to run and in case one of the tests fails the team will know.
p1necone 4y ago
(well written) tests tend to fail (or fail to compile) if they're 'stale' though, so they force you to maintain them just like other code. (I'm not arguing against writing comments though - the 'they'll get stale' thing is not enough to make them not valuable)
- hbrn 4y ago
  I don't see a difference. If you write good tests and use a tool (CI) that detects them going stale, tests will never be stale. If you write good comments and use a tool (code review) that detects them going stale, comments will never be stale. In order for tests to not get stale, you need perfect (well written) tests. In order for comments to not get stale, you need perfect code reviews. Neither of those exist in real world: code reviews are done by humans, tests are written by humans.
randomdata 4y ago
> Better not write tests either, because those will become stale too. They do go stale, but tests were invented exactly so that your documentation is able to alert you when it has gone stale. Their existence rests on being an attempt to solve to this problem.
jrumbut 4y ago
The difference between tests and comments is that comments become stale silently.
- hbrn 4y ago
  Only under assumption that you are writing perfect tests. But if you are capable of writing perfect tests, why haven't you written perfect software in the first place?
BurningFrog 4y ago
When tests go stale the build goes red, and you know to fix things. Comments transition from truth to lie without any indication.
- vkou 4y ago
  > Comments transition from truth to lie without any indication. Only if you don't do code reviews. The reviewer should be checking for this.
- still_grokking 4y ago
  Only if you don't maintain your code. Guess what: Comments are part of the code. Like all other documentation!
  - BurningFrog 4y ago
    Snark aside, I think we can agree that there is nothing automatic telling you when a comment is out of date. If you have a strong discipline of manually checking every possibly relevant comment with each review, I can see how that can mostly work (manual human checks are never perfect). I've never seen anything close to that process, so it's hard to know how it would work. It seems to require a lot of discipline and effort.
  - deleted 4y ago
    [deleted]
- linuxftw 4y ago
  This was true before git blame. Now I can see when the comment was created and the original code it described if I have any doubts about the veracity of the comments.
  - kazinator 4y ago
    If you have git blame, you can see a detailed log messages pertaining to the commits which touch some lines of code. You don't need it to be littered by comments. You seem to think that git invented blame. This appeared in previous version control systems, e.g. "cvs annotate" whose synonym is "cvs blame".
deleted 4y ago
[deleted]
q7xvh97o2pDhNrh 4y ago
Why stop there? The code will become stale, too. Best to not write any of that either.
hayst4ck 4y ago
I don't think your comment tries to paint the best case for the point of view you are opposed to or show an understanding of the philosophy you reject. Tests represent truth in the same way code represents truth. In many ways the tests represent truth more than the code represents truth. Tests state "this is what I want" and then interrogate the code to verify that the code itself does what I want. Tests by definition can not be stale (unless they are never called). The ruby community is where I first learned about test driven development which is philosophically the idea that tests are the highest level of semantic importance. There are DSL's in ruby land for writing tests like you might write comments: https://semaphoreci.com/community/tutorials/getting-started-with-rspec https://semaphoreci.com/community/tutorials/getting-started-... If tests describe what you want, and code describes how it happens, then the major piece left is why it is the way it is, which almost everyone in this thread agrees is the most important thing to comment.

sky_rw 4y ago

Rails developers (myself included) are lazy by design, and thus eschew anything requiring redundant work. Most operate under the principle that "it was hard to write, it should be hard to read"

TedDoesntTalk 4y ago
[flagged]
- the_sleaze9 4y ago
  Personal attacks aren't kosher at Hacker News.
  - TedDoesntTalk 4y ago
    It’s not an attack. It’s an observation based on his lack of team awareness. One of the marks of a senior engineer is someone who is aware he’s part of a group and strives to contribute to a group, rather than a soloist mindset. Call is social maturity if you like.

makeitdouble 4y ago

> Maintaining code is just... work. You just do it. There is an argument about reducing the amount of work. On the staleness of comments, it's a real thing. In particular, on comments explaining design decisions, they will often touch on aspects of the system that are outside of the specific method they are attached to, and nobody will go back to them to rewrite all that prose. We had a project with a ton of documentation written in the first 2 years, and as engineer count grew, these comments just disappeared as again and again they were causing misunderstandings, and actual documentation was already written in the internal wiki as each refactorings and new features were discussed and designed. It's not just a rails thing, and after a while people stop trusting comments altogether, which make updating them a chore more than anything.

davidw 4y ago
> actual documentation was already written in the internal wiki I think that's a reasonable approach if it's easy to find the relevant section of the wiki that describes the code you're looking at by searching. Or just have a comment in the code that points to the wiki. The important thing is to document the "why's".