Awesome! This seems to basically exactly summarize what I think about comments; will try ty pass it around to coworkers who don’t see point in commenting.
Some extra notes I did not seem to see mentioned:
This is fantastic, and I really liked the categories and justification for various types of commenting. One thing I would like to point out is that I think the level and types of comments have to be a function of the engineering team.
For instance, adding design or function comments to the codebase on a team that isn’t already doing it or has no interest in starting to do it, will lead to outdated and stale comments. I think Redis having a BDFL like Antirez really helps here because the BDFL can set the style of the codebase and everyone has to follow it.
Stale comments can be really dangerous in a codebase, so I would say that if you are on a team with very poor code hygeine, it might be best to stay away from certain types of comments.
Unfortunately, I don’t know how to get a team to start caring about hygeine. I’ve seen bugs due to poor hygiene cost real money and yet nothing changes and it is chalked up to the reality of software. Hygeine is tough to maintain and almost impossible to start doing once it has been neglected for enough time.
Seems I can’t open the website on my iPhone, running 1Blocker with default settings. I just get a title. Is anyone seeing the same?
Update: In an ironic turn, once I ticked off “Block comments” category in 1Blocker, I could access the site.