Tom Gardiner

Software Ideals and Standards

Disclaimer: This post is rather subjective. My thoughts may change drastically in the future, but I figured it would be nice to have a record of where my mindset is at in terms of writing code, as of July 2021.

---

I believe that software should be written as efficiently as possible. Electron and other Chromium-based applications, in the modern world of computing, are a shameful display of how lazy we have become as developers. Slack is the age-old example of one application which uses close to one gigabyte of memory - yet it's just a text-chatting app! The Windows 95 installer is 30 MB, and your favourite way to communicate at work uses more than an entire operating system? I will happily admit I enjoy writing JavaScript as a way to control a user-interface, but sitting most applications atop Chromium in some form, these days, is a disgrace.

I also believe that one should not intentionally write generically abstracted code with the belief that this code will be reused lots of times. In some cases it absolutely makes sense, however if you have been tempted to abstract a function away to "make life easier in the future", please definitely consider if that is really what you need, or if specific code that you might end up copy-and-pasting later on will do the job just fine. More often than not, the code you end up writing will be complicated and ambiguous, and will take a lot longer to write due to the nature of it being non-specific, and subsequently will make it more difficult to read if someone else joins the project. Later on, if you were to finally reuse these functions, chances are you'll need to add many extra optional parameters, with very specific edge case conditional statements, therefore defeating the purpose.

Furthermore, whilst it is good to write very short and simple functions, I believe that any given file should not consist of only one function. I have seen this many times and am guilty myself, but when a directory consists of several files where all the related functionality is fragmented between them, and sometimes having files consist of only ten lines or so, it makes understanding the flow and logic more difficult. Believe it or not, it is okay to have a code file several hundred lines long, if all the functions inside it are directly related to one another - otherwise you'll find yourself context switching quite a lot.

The idea of not writing comments because the code is "self-documenting" is alright in some cases, but have you ever seen a function with blocks of code separated by nicely written, genuinely useful comments? It's quite amazing to see, and I think the ability to write such comments is a skill worth persuing. It's not a case what the code is doing - that's usually obvious (hence the "self-documenting" part) - it's the *why*. Maybe you've started work on an existing project and a hypothetical "status" field on some record needs to be set to the number 2. Is it at all obvious why the number 2 is used? What does 2 represent? Adding a comment there can be very useful.