Writing Better Code

by Zac

As I gain more experience as a developer, I'm always on the look out for ways to improve my code. Part of this might be that I come from a non-traditional learning background (read: no formal computer science education), and I want to bridge the gap in as many ways as I can. In the spirit of doing this, I've found the following concepts have really helped to make my code more readable both for myself and anyone who has to maintain what I've written. So here they are in no particular order:

Naming Variables

Bad variable names are something that will continue to haunt you for the duration of a project so care should be taken to make sure they're both descriptive and concise. When I first started programming, I was often confused by code snippets that used short meaningless variables like 'a' or 'b' so my initial reaction was to write longer, descriptive names to make it easier to understand what was going on. That's well and good, but longer names are a huge pain to have to continually type out and can actually detract from code clarity rather than add to it. The key is to strike a balance between keeping the name short and sweet, but also letting a future reader know exactly what value the variable should hold.

const a = 3600; //not descriptive enough
const numberOfSecondsInAnHour = 3600; //overly descriptive
const hrInSeconds = 3600; // just right

Along those same lines, I like to describe boolean values in a human readable format that makes it easy to ascertain the variable type.

//don't do this
let user = false; 

//these are better
let isUser = false;
let isActive = true;
let hasMoney = false;

Naming a boolean as 'user' is confusing because it implies that the var should hold some actual user info, not a binary description of whether someone is a user or not. By prefixing it with the appropriate verb, a reader can easily infer the type.

Use 'const' over 'let'

Make the effort to avoid using 'let' whenever possible in favor of 'const'. In JavaScript, 'let' is a mutable variable declaration, while 'const' is immutable. If variables are mutable, they can be changed after they have been declared. This is a necessary part of programming, but it is always best to declare things that should not change as a constant. That way, other programmers can trust that you won't try to mutate the value somewhere else in the code. A 'const' will hold the same value it was declared with. For example, functions should always use a 'const' declaration because the code would be a mess if something declared as a function on line 10, suddenly held a number on line 20 and could no longer be invoked as a function. That would be hard to understand and harder to debug. So, always choose to use 'const' as a first resort, and only switch to 'let' when it's a variable that you know will need to be altered.

Writing (Useful) Comments

This is one that people seem to be divided on. On one hand I've heard that good code should be self documenting and that comments are a crutch for people that need to explain their bad code. I think the idea of self documenting code is nice but I often come across code that could benefit from a comment.

I think striving for simplicity is always the primary goal, but clear comments make decent code into great code. The best piece of advice I've gotten is that comments should explain the why,  not the what. It should generally be clear what you're doing, but if you can comment to explain why you're doing something a certain way that would be helpful for someone else reading your code later, then you should do so. And as with many things, less is more.

Avoid Nesting Your Logic

if(num > 10){
  if(num < 50){
    if(isSecretNum === true){
        return "You've guessed correctly!";
       }
  }
}

The example above is tiny but the bigger and deeper the nesting becomes, the harder it will be to read and eventually debug. If you ever see yourself writing something like this, there's probably a better way to do it. (See below).

if(num > 10 && num < 50 && isSecretNum){
  return "You've guessed correctly!";
};

Review Your Pull Requests Before Submitting

This isn't necessarily a way to write better code but it is a way to save yourself some embarrassment and avoid wasting your co-workers' time. When you're ready to push your code to Github, go through everything line by line and see if there is anything you can clean up before showing it to someone else to review. Do you have console logs that should be removed? How about pseudo code comments that you made when doing a first pass? Do your best to ensure that when you ask someone to review your PR, it's free of any mistakes as far as you can tell.

Incorporating these things into my workflow has definitely improved my skill as a developer. As I learn new things, I'll try to keep updating this post.