Clean Code Is Important

The code below is taken from an internal dashboard I use for Ethical Web Design, and would be a good example of what I call clean code.

It's clear and easy to read - almost like a sentence in English - and I'm avoiding unnecessary nesting by checking for fail conditions at the top of the function.

/**
 * Checkout the specified branch, optionally creating it if it does not already exist.
 *
 * @param  string  $branchName
 * @param  bool    $createIfNotExists
 * 
 * @return bool  Did the action complete successfully?
 */
private function checkoutBranch($branchName, $createIfNotExists = false)
{
    if (!$this->isGitRepo()) {
        $this->output("Cannot checkout {$branchName}, you are not in a Git repository.");
        return false;
    }

    if ($this->isDirty()) {
        $this->output("Cannot checkout {$branchName}, repository is dirty.");
        return false;
    }
    
    //...

    return true;
}

What does the internal dashboard actually do?

It effectively handles all of the intricacies of GitFlow for me, so I can write a single command - telling it what I want it to do - and it ensures that everything that needs to get done ... will get done. We're all imperfect humans, and we all forget things. It's truly amazing that as part of our job, we can write software to solve even that problem.

Writing clean, readable code involves a lot of very small decisions

But the point of my blog post today, is that along with adding a few new features to my dashboard, I did a lot of internal clean-up. Indentation, extra debugging messages, abstracting out common code, and other various changes that will help me in the future. And I took the time to do so because it's important.

Any time on clean-up, refactoring or legacy-removal tasks is time well spent. I'm sure many will agree with me. The 30 minutes that I spent today cleaning up my code will save me countless hours in the future. Especially when (not if) requirements change and I want to rewrite it.

It's important to allocate time to doing this.

Back to that internal dashboard

On a side note, the features I added to my internal dashboard were:

  • Auto-detect webpack, so that assets can be versioned and minified automatically as part of the release process.
  • Auto-detect composer, so that when I'm task switching between branches, I automatically run a composer install for the projects that use it.
  • Auto-detect Laravel projects, and prompt to roll migrations and seed the database when I'm task-switching.

I might open-source the tool in the future, but for now it's just something I've been slowly building up for private use. If you would be interested in something like this, hit me up and let me know, it may give me some motivation to open-source it sooner if I know you're going to use it ;-)

Have a good weekend.

Development Tips Internal Dashboard