1. 11
  1.  

  2. 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.

          2. 13

            listen to everything and ignore 90% of it

            This is probably good advice. I’ll apply it to this article.

            1. Avoid comments.

            This varies heavily by language. If the language features documentation strings, as Common Lisp does, then it’s fine advice and that’s how I operate; if it lacks them but still has many first-class structures for documenting intent and whatnot, such as Ada, then I’ll write less comments, but perhaps one or two where I think it’s fine.

            It’s just my preference, but I’ve never been fond of names such as getUserAndAPITokenFromLocalStorage and would rather read the comments, but I’d rather avoid reading JavaScript at all, so this could be seen as a superfluous aside.

            1. “Never use a plugin you would not be able to write yourself.” (credit to Jamis Buck).

            I don’t see any issue with this advice, amusingly. This seems like programmer common sense, perhaps, or should be. I’d prefer to use libraries for what I don’t want to write, not what I can’t, such as implementing a complex protocol I need to interact with but don’t otherwise care about.

            1. Use simple tools.

            Without any malice, this is the worst advice in the article and I vehemently oppose telling new programmers this. Ostensibly, the computer is a machine that is to reduce work on the human and aid in tasks; this advice runs counter to that. Firstly, Emacs is just one tool that enables one to use a remote machine with local tools with its Tramp mode; there are undoubtedly others. Secondly, I’m of the opinion that a programmer can and should gradually replace tools they use with ones they’ve written themselves, although I understand others would see differently. I’m doing this in my own way, gradually, but at least I’m making some progress.

            I don’t in any way support the idea that whatever dumbassery the UNIX or Microsoft gods decided decades ago is the baseline and anything on top of that is superfluous. That is stagnation. That is awful.

            About 10 years ago, I remapped Caps Lock to Ctrl on my keyboard. I like that position so much better. Now I can’t use anyone else’s computer without either getting frustrated or going into their settings and remapping the keys on their computer. Is my enjoyment worth this? Probably not.

            Is this a work machine you’re using for hours every day or a toy? Would, in any other setting, a professional who spends years or decades of his life doing something be faulted for customizing his tools to work best for him and remove strain or friction?

            I suggest one reads what Erik Naggum had to write about this general idea: https://www.xach.com/naggum/articles/3065048088243385@naggum.no.html

            1. Working code is good code.

            I’d argue that working isn’t the only qualification for good code. Good code is eventually finished and requires no further changes to accomplish its purpose elegantly.

            1. Don’t be afraid to delete code.

            I have no argument here, really.

            1. Prefer data.

            This isn’t bad advice, with how it’s phrased. I suppose I would’ve used this: ``Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.’’ –Fred Brooks

            1. Always do the hard thing.

            To me, this is the most original advice in the article, but perhaps I’m simply differently read. I’d be wary of a system that is poor at the outlook, though, such as tens of thousands of lines of some poor language, or really tens of thousands of lines of anything.

            This sums my thoughts on the article; perhaps someone will find this a pleasant read on its own or a good critique. I’d be glad for my articles I submit here to receive the same attention, certainly.

            1. 3

              “Never use a plugin you would not be able to write yourself.” (credit to Jamis Buck).

              I don’t see any issue with this advice, amusingly. This seems like programmer common sense, perhaps, or should be. I’d prefer to use libraries for what I don’t want to write, not what I can’t, such as implementing a complex protocol I need to interact with but don’t otherwise care about.

              This literally goes against human nature, this recent Human Brian podcast[0] explores why humans depend on others before them to solve/understand things that they can build upon.

              My immediate reaction to this comment though was: if you wanted to make a new car seat, would you (or do you need to) know how to make the engine, frame, wheels, etc? I would argue “no”, and that depending on systems you don’t understand is nominally ok. Another silly example: I depend on my local grocery store to sell me food, without me knowing about how to make most of it myself..

              1. https://www.npr.org/2019/01/11/684435633/how-science-spreads-smallpox-stomach-ulcers-and-the-vegetable-lamb-of-tartary
              1. 2

                To “be able to write something yourself” covers a very wide range of possibilities. Do I need to be able to write it myself in a reasonable timeframe? Do I have to already have the knowledge to write it now, or can I take time to study it when I actually need to write it? Given enough time, I should be able to learn most things, so that would actually rule very little out.

                I think a more useful focus is “Can I fix problems in a dependency if I discover them?”. For me, this means preferring open source dependencies, as without the source you are at the mercy of the vendor (who may cease to exist). It also means preferring dependencies with simple, well designed code, which I should be able to understand with a little studying, but without necessarily having to have the expertise right now.

              2. 2

                I really appreciate your thoughts, even though we’re likely to disagree on many things. I only want to reply to one thing – about the keyboard. I remapped Caps Lock to Ctrl on every machine I use, including my work machine I use for hours each day. If I could go back 10 years and tell myself not to, I would. I use other people’s computers a lot more than most people, though; I pair-program with students on their computers all the time.

                I really like your opinion that programmers should replace tools with ones they’ve written themselves. It’s bold and solid advice.

                1. 5

                  I pair-program with students on their computers all the time

                  Yeah, that’s a bit of a special case. I use other people’s computers… approximately never, so I’m very happy with the Colemak layout and a CapsLock that acts as both Ctrl and Escape and shifts that act as parens on their own.

                2. 1

                  Upon reading blog post’s point 3. I got the “somebody is wrong on the Internet” rash.

                  Thank you for posting a soothing response, I lathered it in generously.

                  1. 1

                    You are right about 3.

                    If we would not progress with the tools the recommendation would still be “use sh instead of the fancy korn shell or crazy bash”.

                    The key is - as always - balance. Be careful about the bleeding edge but don’t limit yourself to the largest common denominator just to be perfectly safe all the time.

                  2. 5

                    The “use simple tools” part is good advice, though some of the accompanying explanation is a little confusing — vim is mentioned as someone else’s “special tool”, but also as a “simple tool”. I’m not sure why zsh should be ignored before the developer is comfortable with bash; there’s a lot of overlap between the two.

                    And then there’s this part…

                    About 10 years ago, I remapped Caps Lock to Ctrl on my keyboard. I like that position so much better. Now I can’t use anyone else’s computer without either getting frustrated or going into their settings and remapping the keys on their computer. Is my enjoyment worth this? Probably not.

                    …Which reminds me of this old favourite SJL comment:

                    I can count on my balls how many times I’ve sat down to program at someone else’s computer in the last five years. It just never happens.

                    https://www.reddit.com/r/vim/comments/2c3cuu/a_quick_tour_of_steve_loshs_massive_vimrc/cjc4jnj

                    1. 2

                      Good article! Agree with a lot of this.

                      However, I really rather prefer the commented version in the initial example.

                      1. I get to understand the writer’s intent.
                      2. It reads procedurally so I don’t have to jump around the file to read it as the computer would execute it.
                      1. 2

                        About 10 years ago, I remapped Caps Lock to Ctrl on my keyboard. I like that position so much better. Now I can’t use anyone else’s computer

                        Oh yeah? I type Dvorak. Using somebody else’s computer turns me into a hunt-and-pecker, and if I ever do find a typing rhythm, I end up slipping into dvorak. When the Greek gods punish me internally, I’ll have a QWERTY keyboard on my computer, but I’ll have to give verbal instructions to someone using a Dvorak layout (but with QWERTY keycaps) to walk them through typing a series of shell commands, and even Prometheus is gonna go, “Whoa, what’d you do to piss the gods off for that?”

                        1. 1

                          Lost me at “avoid comments”. Maybe just avoid verbose comments.

                          1. 1

                            Use what comes on every system first: bash and vim.

                            That’s just like, your opinion, man.

                            1. 1

                              Avoid comments.

                              Highly disagree, write clear code and supply with comments where necessary. I dislike extremes, they’re mostly wrong.