1. 19

    This is all good advice, but I disagree with “1. Avoid comments.” Self-documenting code is fine if done conscientiously, but I still prefer to follow the age-old advice: “Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.” – in the long run it’s easier for a mind to understand human language than for it to parse everything happening in code.

    1. 15

      The removed comments include things like “(which isn’t very secure, but works for this)” and “JavaScript’s this keyword doesn’t point to what you might want it to always, and we can’t use these in event listeners”, which IMO is important information that was lost in the translation to self-documenting code.

      1. 5

        100% agree with you about the first comment, though I think the second comment doesn’t belong there, since you’ll have to otherwise repeat the same comment in every “component”. The information is still very important though and should definitely be highlighted in manuals/docs.

      2. 10

        The main problem with most comments is that they describe what the code actually does, which you can usually work out by reading the code. Useful comments explain why the code needs to do what it does, or why it does it in a non-obvious way. There’s only so much of that that you can convey by variable naming.

        1. 5

          Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.

          While its a funny quote and all, I do not recommend seriously adopting this as a mentality. Its a recipe for imposter syndrome, especially for newer developers. Even if you don’t personally have problems with imposter syndrome, knowing others on your team have this type of mentality can be intimidating. Think about it like this… why would I ever write code if I knew there was a chance the person inheriting it would come to my house and murder me? Taken less literally, why would I write code if the person inheriting it is going to resent me for it?

          We should all try to write better code, but as the person inheriting code it is your responsibility to not be a violent psychopath. I mean that both literally and metaphorically.

          1. 2

            I thought that this was a satirical article, so I read the next few points as

            • “don’t waste time doing something someone else has already done”
            • “don’t be afraid to use tools that make your life easier” (especially since he ads ‘vim’ to the special tools list, but then says use it…)
            • “just because code works doesn’t mean all is good”
            • “don’t overuse version control, especially for very temporary changes”

            the last two then really confused me, but it’s interesting how you can make a “wisdom” for each side of the argument.

          1. 2

            Painting my upstairs hallway. Had a landing installed for upstairs laundry around a year and a half ago and never got around to painting the new walls.

            Apart from that, just hunkering down for the winter weather headed my way (midwest).