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.
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.
(I'm not arguing against writing comments though - the 'they'll get stale' thing is not enough to make them not valuable)
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.
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.
But if you are capable of writing perfect tests, why haven't you written perfect software in the first place?
Comments transition from truth to lie without any indication.
Only if you don't do code reviews. The reviewer should be checking for this.
Guess what: Comments are part of the code. Like all other documentation!
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.
You seem to think that git invented blame. This appeared in previous version control systems, e.g. "cvs annotate" whose synonym is "cvs blame".
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'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.
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".
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.
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.
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".