in which an internet-using agent whose credibility is a random variable throws yet another hot take on top of the gargantuan pile, and then fails to engage with any reader feedback.

extra credit:

  1. are docstrings comments?
  2. what would Knuth do?

A continual sine-wave of articles telling us to comment our code, then delete it.


My rule is comments should:

  • summarise what something does, or
  • explain why something is the way it is If it’s not a summary or a why then it’s not adding value

if you are working with coworkers who are doing such slipshod work as to not change a comment two lines away from their modification, and the code review practices you have in place are not adequate to catch such a thing getting merged in, there are no guidelines that will help you, sorry


IME it’s more that you just don’t see them. Comments are usually only useful the first time you read the code. Once you’ve read them and understand the code they’re no longer useful, becoming little more than noise. Your brain will then eventually wire itself to filter out that noise.


I mean, I get how this is how I might not think to keep it up to date–but I would never submit a pull request or approve one without checking this kind of thing. The balance of requiring effort from the writers, maintainers, and readers of code is always in flux, it’s true. But if you’re building something big enough that people working on it can forget how a part works, you need comments, and you need them to be good, and, moreover, the kind of people who don’t care about keeping comments up to date are not going to be keeping method names / abstractions up to date either.


You can’t see what you can’t see. Haven’t you ever proof-read a sizable text you’ve just written, just to discover later that you still missed a gazillion typos? Or looked all over your house/apartment for your keys, only to discover they’ve been in your pocket or right under your nose the whole time? Your brain is very good at fooling you into thinking you’ve checked something when it already “knows” what the result will be.

It’s true that people who don’t care about keeping comments up-to-date probably don’t care about keeping identifier names up-to-date either, or accurate naming to begin with. I’ve met several people like this and I hate their guts. But unless the reviewer is also a sloppy bastard it should get caught in the review. Comments being effectively invisible makes this much less likely.

I’m also not saying to never write a comment, just that they should be avoided as much as possible in favor of descriptive code. Comments aren’t always bad, but they’re usually worse.


I was recently in a project where they had a git hook to enforce that every method, class and module has a documentation comment.
So, even a method Db.init() had to have a comment “Initializes the DB.”.

As a result, the quality of those comments in general was awful. If you have to fill in 20 documentation comments, you’re not going to go into huge detail, even when in some places a description might actually make sense.

And then as a result of that, 95% of comments were not worth reading, which meant no one read them, which meant no one fixed them or complained about them being bad in code reviews.

It was basically just wasted time, that we had to fill those comments in.


This is why we still need comments.


Developers remain best-utilized writing code, architecting systems, and creating tests.

It would be nice to explain more how tests fit into this comment vision.

The ideal number of comments is zero. It was hard to write, it should be hard to read.


deleted by creator

General Programming Discussion

    A general programming discussion community.


    1. Be civil.

    Other programming communities:

    • /c/rust
    • /c/python
    • /c/powershell
    • /c/haskell
    • /c/fpcomplete
    • /c/cpp
    • /c/c_programming
    • /c/julia