Clean Coding

Coding Aug 25, 2021

As a software developer there are many, many ways to write code and there are many standards used in various companies even industry standards for some languages. Through experience you learn what works best for you and what works best for working with other people as well. The idea behind the term "clean code" is writing code that's nice to look at, well thought out and easy to read. When I talk with other developers I can immediately tell their experience level based on what their code looks like because this is one of those things that's best learned through practice and experience. I want to try and communicate some of the things that I do with my projects both personal and professional that you might consider in your own work. With this article I will cover general concepts and try not to be language specific, I will use Javascript in the examples but these concepts are mostly transferrable to other languages as well.

Spending time writing better code will not only help your fellow team mates but it will also help you be far more productive because you will spend far less time looking back and trying to figure out code you haven't seen before or code you haven't seen in a while.

Spaces, New Lines, etc.

There seems to be a hatred for using too many spaces, new lines and other non-required items in code that's perpetuated online and I believe that it's based on languages like traditional Javascript that you had to take an extra step and minify the code to get rid of things like this and thus many people had large executable code when it needed to be small. Here's the thing though: It doesn't need to be small when you're working on it. Leaving out spaces and new lines simply makes the code harder to read and if you have a lot of really complex code in a large file the small pause it takes to read really adds up. Please don't forget to minify your code when you ship to production though 😅

I usually advise that you write code like it's meant to be read and write it so that it's very easy to understand for everyone. This means adding new lines to separate things sometimes or adding spaces where spaces make sense.

Here's an example of what I would consider "good" practice and "bad" practice read both methods and ask yourself what is easier to read. Since this is a single method the difference may seem small but then imagine a 3000 line file with hundreds of methods like each of these items.

class Example { 
  constructor() { }
  
  good(arg1, arg2) {
    if (arg1 === 'Test') {
      return 0;
      
    } else {
      return 1;
    }
  }
  
  bad(arg1, arg2) {
    // Inconsistent spacing
    // No space after `if` 
    // No new line before `else`
    if(arg1==='Test' ) {
      return 0;
    } else {
      return 1;
    }
  }
}

We can further this subject with some more examples, such as wrapping long lines so that they are lined up with other items:

// The combination of multiple long cases here makes this line 
// really long, which makes this slightly harder to consume as 
// someone that's trying to read and understand the code 
if (reallyReallySuperLongCaseName() && reallyReallySuperLongCaseName2()) {

}

// Here we compact the same code so that it can be read at a 
// glance and we have reduced the amount of time it takes to 
// read this code thus made eveyone's job slightly easier
if ((reallyReallySuperLongCaseName()) && 
    (reallyReallySuperLongCaseName2())) {

}

Another place that I find this a lot is in switch statements because it's pretty flexable in almost every language (especially Javascript) here's an example:

switch (test) {
  case 'bad': 
    many();
    many();
    complex();
    operations();
        
    if (maybeEvenAFewIfs()) {
      return 1;
    }
    
    break;
  
  // Just use curly braces on long switch cases ffs =^)
  case 'good': {
    many();
    many();
    complex();
    operations();
        
    if (maybeEvenAFewIfs()) {
      return 1;
    }
      
    break;
  }
        
  case 'good-2': return singleLine(); // fine..
}

Comments

Commenting is a valuable tool for developers, similar to spacing and new lines there seems to be many developers who just don't comment or learned that it's not required to write good comments. I'm guilty of this myself in many cases and strive to do better because I believe that it makes a huge impact not only with sharing code with others but also going back to old code much later and being able to read and understand what's going on. The faster you can read and understand code the faster and better you can get things done with less refactoring.

There is such thing as over commented code as well so we should be cautious to write high quality code and use comments where we think they will be helpful. There's also good and bad comments, for example if your method documentation comment just repeats the method name and arguments without explaining what it does or what's expected then it doesn't add any value to your codebase.

As mentioned before commenting is best paired with high quality code, so you need to make sure that you're naming methods, functions, variables, etc. with names that make sense to their function and not obscure names that only you know.

Consistency

Above all else being consistent with the way you write your code is a massive improvement in itself. Pay attention to your code and how you write it take the time to develop consistent habits regardless of how long you have been programming there's always room to improve. If your code is spaghetti and constantly changing all the time it's very hard to read.

Think about it like this:

It's much easier to read a book written in one font than read a book written in many fonts that switch every few paragraphs.

Your work has to be read; It has to be read by you and if you're working with others it has to be read by them as well sometimes this is a huge team full of many different people on many different experience levels and sometimes it's just one or two people. Making sure you're consistent is a huge improvement to making your code easy to read for everyone, including yourself.


Discussion

I'm interested to hear thoughts and comments about clean coding, which methods you use in your work and what you think about my suggestions. I'd like to make this a series since there's so much to cover and it's fairly complex to explain so look out for more articles about clean coding soon!

Tags

Cryptobyte

Senior Software Developer working with software since age 17 (all the way back in 2008!)

Comments

Sign in or become a Cryptobyte member to join the conversation.

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.