Comment by atoav | Hacker News Reader

Comment by atoav | Hacker News Reader

Parent Full thread

This is an issue of bad habits. "I am just quickly going to change this tiny, little thing" — you are saying to yourself and forget about the existing comments.

Some tips for better habits:

- whenever changing existing code, read the comments

- if you know the changes are going to be big, just delete the old comment first

- if the changes are minor, but change the code add a TODO: check comments on top of the existing comments

- try to keep comments tied to the thing you are commenting, comments that describe interactions between components go to the outside scope, this way there are less surprises where comments need to be updated

- consider writing comments describing what you are going to do before writing the code. On top of writing the comments this acts as an additional reality check and quite often leads to better code as well

Why cant we have comments that are tied to a hash of the block of code the comments are refering to?

Have editor plugins that highlight if the hash no longer matches, then you can evaluate if the comment needs to be updated or not and update the hash.

This would eliminate the problems raised about working on teams and people not following procedures.

This is fine if you're the only person to ever touch this code. But if other people will modify the code you can generally not rely on them following your idea of "good habits"; therefore it's sensible to help them not shoot themselves in the foot.

> This is fine if you're the only person to ever touch this code. But if other people will modify the code you can generally not rely on them following your idea of "good habits";

Teams of two or more individuals can establish norms with only a little more difficulty than individuals, and can provide accountability to those norms better than an individual.

Unless you are editing somebody elses code, any team working on code can (and in my opinion: should) agree on some common standards. If you are not taking a day to discuss this, you are saving time in the wrong space.

It should be easier to keep comments in code multiple work on up to date, since there would be code review that lets everyone keep each other honest.

Reply on news.ycombinator.com