DEV Community

Matthew Palmer
Matthew Palmer

Posted on • Edited on

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)
}
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (8)

Collapse
 
kais_blog profile image
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.

Collapse
 
raddevus profile image
raddevus

That's a good tip to know. thx

Collapse
 
matthewpalmer9 profile image
Matthew Palmer

Thank you, Kai! That is very helpful.

Collapse
 
pfiver profile image
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();
Enter fullscreen mode Exit fullscreen mode

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

Collapse
 
matthewpalmer9 profile image
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.

Collapse
 
beaufortaustin profile image
Austin Beaufort

Nice writing!

Collapse
 
raddevus profile image
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

Collapse
 
matthewpalmer9 profile image
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.