Best Code Practices

Introduction

Coding in any language needs some type of order. Strangely enough, not all developers truly understand how important it is to maintain logical naming conventions, a lack of excessive whitespacing and plenty of comments where needed!

This post is inspired by the content posted by Shannon Beach on LinkedIn

Whitespacing

I've spoken with senior/lead developers on LinkedIn who seem to have a few horror stories concerning whitespacing. If you're unfamiliar with what it is, it's literally the space between blocks of code. Here's an example:

const someFunction = (params) => {
    let someVariable = someAssignment.goesHere(params)
}
    <---- THIS IS WHITESPACE ----> 
    <---- THIS IS WHITESPACE ---->
const anotherFunction = (params) => {
    return someFunction(params)
}

Separating blocks of code by a single whitespace is completely alright -- even encouraged for readability. However, if you are separating these blocks by 10 or even 15 lines of whitespace, this is not ok. One specific connection of mine mentions that they will immediately stop reading and drop an applicant for this alone. Excessive whitespacing is just a horrible idea. It is best to avoid it at all costs.

Naming conventions

What we name our functions and methods matters. The point being that you want to tell a story. If you have a method that is meant to gather and count how many apples you have in a basket, there is a story that comes along with it. You'll grab a basket from your belongings, you'll travel to an apple tree, you'll fill your basket and proceed to count how many you have. How could we translate this process into a functional story?

How does this look?

let appleCount = 0;

const beginApplePickingFunction = () => {
    grabBasketFromGarage();
}

const grabBasketFromGarage = () => {
    walkToAppleTree();
}

const walkToAppleTree = () => {
    pickAppleFromAppleTree();
}

const pickAppleFromAppleTree = () => {
    placeAppleInBasket();
}

const placeAppleInBasket = () => {
    appleCount++;
    returnApples();
}

const returnApples = () => {
    return appleCount;
}

beginApplePickingFunction();

Without even seeing detailed code, we are separating each action by concern. You know exactly what is happening and you might even know which function to check when something doesn't go right. Why? Because it tells a story. If you can tell a story with code regardless of its inner complexity, you make the lives of your entire team easier.

Comments

Commenting your code is like the sweet nectar for understanding code bases. Often times we can find more complex actions and patterns within a block of code. Without comments, we would likely have to study each block of code until we find what we are looking for. With comments, you might still need to study a block of code to know what it could be doing wrong, but now we know exactly which block of code as its functionality is clearly define by the story its comment is illustrating.

Conclusion

I hope that this blog helps some of you out there! Whether you're a new or seasoned dev, you can either use this or send it to someone you feel might benefit from this information. 😉 All the best, my friends. Leave a comment if you've got something else you'd like to add!

Comments

[Kai]

Just a tip, you can add a language tag to highlight code blocks in markdown. Simply add js or any other of the available languages after your first set of backticks. Like so ´´´js. Note that the backticks should be the other way around. I don't know how to properly escape them in markdown.

[raddevus]

That's a good tip to know. thx

[Matthew Palmer]

Thank you, Kai! That is very helpful.

[Patrick Pfeifer]

Very nice post. The ideas resonate well with me. Whitespace is an important aspect of code and I often find myself having very different preferences than other team members. I do not like too much of it in-between methods either.

---

However, I need to bring up something important about the example you are giving for the "story telling" aspect. I think naming and story telling is equally if not more important than whitespace.

But the example unfortunately clearly violates the SLA principle described by Kent Beck, Neal Ford, Robert Martin and many others. There are plenty of articles about it. Here is a random link.

I think this is one of the most important principles. And the way in which it is violated in the example is such that the (arrow) functions are not doing what they should. Judging by their name and the fact that they are (arrow) function, they are IMHO supposed to implement functionality. Instead, they define the order of the execution, e.g. they orchestrate functionality. As a consequence, the order of execution will become very hard to understand and change as soon as more details (code) are added to the "story". This is mainly because there is no separation between "orchestration" and "implementation". And those should be separated, because two things that are not at the same level of abstraction. 1)

To make a long story short, this is how I would suggest to improve on the above mentioned issues:

class AppleHarvester {

    appleCount = 0;

    gatherAndCountAll() {
        grabBasketFromGarage();
        walkToAppleTree();
        while (treeBearsApples()) {
            pickAppleFromAppleTree();
        }
        placeAppleInBasket();
        return appleCount;
    }

    grabBasketFromGarage() {
    }

    walkToAppleTree() {
    }

    treeBearsApples() {
    }

    pickAppleFromAppleTree() {
    }

    placeAppleInBasket() {
        appleCount++;
    }
}

new AppleHarvester().gatherAndCountAll();

1) On a side-note: I very much like Ralph Westphal's thinking about the separation between "implementation" and "integration".

[Matthew Palmer]

Patrick, I really like your insight on this! It's discussions like this that make us all better developers. This is why I love our community. We end up learning so much from each other. Nothing pleases me more than clean code. Your method here saves so much space, and it is definitely something I'm putting into more practice in my own projects.

[Austin Beaufort]

Nice writing!

[raddevus]

This is a great post. I agree, adding just one extra whitespace line per block can make your code far longer and require more scrolling. And, again I agree with the function naming. You should be able to read code like a story and know what it is doing so detailed function names are important.

Are you going to enter the #dohackathon challenge here? I completed my entry yesterday. If you get a chance, check it out and let me know what you think. thx

[Matthew Palmer]

Hi raddevus,

I love the idea of hackathons, but I am far too busy as a father to a 1 year old and with job searching to participate. I'm looking forward to next year's hackathons though! I wont miss those for anything.