1. 31

  2. 6

    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:

    1. When reading/analyzing the code, having “guide comments” has the added benefit of helping to find bugs. Both during review, and also later when debugging some tricky bug, this helps me see what the author intended the code to be, and establishes a “hypothesis” about the following code in my (reader’s) mind. Reading the actual code below works as “an experiment” (in Scientific Method terminology), through which I can now “validate” the “hypothesis”. Notably, it tends then to be easier for me to notice when some parts of the code are “fishy” or suspicious, i.e. unexpected from the my established mental model/hypothesis point of view. This can be a useful hint they may be buggy.
    2. Writing good “function comments” often “automagically” leads me to discovering a good name for the function. I noticed more often than I’d expect, that when I struggle with finding a good name, setting it aside for a moment and focusing on writing a good godoc basically gives me a few of the exact words that are most crucial and best describing for the func.
    1. 3

      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.

      1. 1

        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.

        Stories with similar links:

        1. Writing system software: code comments via azdle 2 years ago | 25 points | 5 comments