Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.


> 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.


When tests go stale the build goes red, and you know to fix things.

Comments transition from truth to lie without any indication.


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.


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".


Put the comments in git commit messages! Ha, that’s a good laugh. There are so many shortcomings to this, I don’t even know where to begin.


Nick checks out?


The obsession people seem to have with squashing commits in git (particularly on merge) means they're right, you can't really rely on commit messages still containing relevant information.


Squashing commits in this way would not have been allowed anywhere I've worked in at least 20 years.

This is a strawman argument.

Let's assume best CM practices (no vandalism of change sets when moving changes among branches), best practices for commit messages and best practices for commenting.

Commit messages win.

Code comments should be like road signs. E.g. how high can your truck be to pass under the upcoming bridge. Not blueprints for the bridge, or paragraphs about why it was built there, what communities it serves. (That information must exist and be available, just not on the bridge.)


I don't consider comments litter. Commit messages rarely have the amount of context needed for a specific block of code.


I write GNU-ChangeLog-style commit messages which mention every function and other named entity touched, added or deleted, with details about why. Between that and the diff, you can figure out exactly what was done and why, matching the comment with specific code blocks.

I've never been disappointed when digging back in history to figure out why the heck something was done.

It would be a strawman of my position to say that I'm favoring zero comments. For instance, a /* fallthrough */ comment in a C switch statement cannot be in a commit comment, not the least reason for which being that compilers look that that nowadays.

Comments should be like road signs. I need a warning about a dangerous curve ahead, not a discussion of why it was built that way.


yeah, if you can do commits per function that would be fine. Most projects don't allow that, everyone squashes commits these days.


If that's an argument so is this: most coders don't like commenting, nobody bothers, comments are haphazard and unmaintained. Just skip them.

You don't seem to have understood my remarks; It's not "commit per function", but cover each function that was touched (or other entity: class, global variable, type, object member) in your commit comment.

When someone does "git log" they should be able to search for the name of a function of interest and see all commits which touch it, explaining what was done to it and why.

Banish squash commits; it's a poor CM practice. If you're not able to get your developers to commit to a good practice, then that's your main problem. You have to fix that before engaging "comment versus commit".


Only if you don't maintain your code.

Guess what: Comments are part of the code. Like all other documentation!


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.


> Comments transition from truth to lie without any indication.

Only if you don't do code reviews. The reviewer should be checking for this.


Why stop there? The code will become stale, too. Best to not write any of that either.


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-...

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.


(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)


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.


> 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.


> 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.


The difference between tests and comments is that comments become stale silently.


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?


> 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.


> 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".


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"


[flagged]


Personal attacks aren't kosher at Hacker News.


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.




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: