a thoughtful web.
Good ideas and conversation. No ads, no tracking.   Login or Take a Tour!
comment
akkartik  ·  4285 days ago  ·  link  ·    ·  parent  ·  post: Yes, your code does need comments.

We've had some teething pains, but that's mostly because of moving servers and foisting git on you :)

In the abstract I care about commit messages far more than I care about comments, because I believe comments are more useful with a timestamp. But it's still been low down my priorities given all the different technical debt we have to pay off. Since I'm already familiar with arc, comments seem mostly irrelevant right now. They'll become important at some point if we need to involve others. Maybe with the API? :)

---

Talking about comments in isolation as a measure of codebase quality is like talking about height in isolation as a measure of mate quality. I think that's what your criticisms boil down to, and they're perfectly valid.

If the goal is to get newcomers to a place where they can meaningfully contribute, that drives everything. Well-functioning small teams rely on interactive discussion to orient newcomers. Since it's not clear that comments would ever replace in-person interactions, the default position tends to be that they're unnecessary/luxuries/evil, and that's reasonable.

In large teams, in-person interactions gradually get expensive, and that causes greater reliance on comments and other mechanisms.

I started out anti-comments, but have reluctantly come around to believing that there's nothing to replace them in certain situations. My current goal is to make the codebase intelligible to others even when I'm not around to explain it. That seems hard enough that I can't afford to be too ideological.

Bottomline: comments are sometimes useful, but there's too much dogmatic thinking on both sides battling over them. Attend to the big picture.