1. 5

  2. 3

    I’ve definitely come to the conclusion that comments are lies. My solution isn’t “write self-documenting code” but just “use types, they never lie”

    1. 2

      I wish it was that simple for me. My day-to-day work is with PHP and JavaScript, both of which are extremely easy to “lie” with. So far the most helpful thing has been using GitHub pull requests as part of our daily workflow. We basically use them as a way to instigate a code review, which usually helps catch this sort of thing before it’s merged into master.

      1. 1

        We enforce reviews before merges, extremely useful.

        We actually use an automated build to test and merge our pull requests. We trigger it after everyone has reviewed and then let it come back to us if it fails to merge.

    2. 2

      For more on the subject of when comments are good and when they are bad, I recommend Clean Code chapter 4 “Comments”. You can read it starting on page 86 of the book PDF.

      The chapter, like the article, concludes that comments are usually bad. It also shows various examples of good and bad comments.

      1. 1

        I personally think this is why comments are “greyed out” in many text editors. When I write comments, it’s typically to write documentation for the code, to be read in a browser or something. Just so people don’t have to read the actual source to figure out how to use my library. So I’d prefer it if my editor greyed out comments, because they frankly have no place in my code but rather as documentation for my code. Therefore, I don’t want them to cloud my vision of what I really need to see.

        1. 1

          Usually documentation generators only read block comments, so it would be possible to grey those out and keep inline comments in a more prominent colour. Although I guess this won’t work for languages like Ruby where people tend to use inline comments for everything.

          1. 2

            Unfortunately, RDoc in Ruby reads inline comments, so I’m stuck with that. But then again, if you’re doing it right you shouldn’t need comments in Ruby :-P (j/k)

            Vim has a nice feature wherein if you write “TODO:” or “NOTE:”, it’ll highlight the word in purple. So sometimes I will leave NOTEs for other devs. In a Rails app, you can read all your todos by running rake notes. Super useful, hardly anyone knows about it :)