DEV Community

Mastering Clean Code: Essential Practices for Developers

Mahabubur Rahman on June 15, 2024

Clean code is the cornerstone of every successful software project. As a developer, your ability to write clean, maintainable code is crucial for t...

Read full post

Red Ochsenbein (he/him) • Jun 16

I have some issues with your examples:

First, in your comments example "Calculate the total price based on quantity and unit price" just simply restates what the function already defines anyways. I'd consider this to be a bad comment. A good comment should state something about the context, about the 'why' this piece of code exists. What it does should be as clear as possible by it's definition.

Also your "Asynchronous Control Flow" example is basically just making the async calls synchronous without good reason. According to the function call whatever the asynchronous code does seems not to be dependent on a previous function call. (If it does, you'd probably have to rethink what you do, because it should probably be batched together into something like a transaction). So, based on that why limit the async code to only one execution at once?

async function processItems(items) {
    const promises = [];
    for (const item of items) {
        promises.push(processItem(item));
    }
    await Promise.all(promises);
}

Is probably closer to what you want. Also - as @thenickest mentioned - it's missing error handling since every async execution could get rejected.

Willian Eckstein • Jun 17

Good I was about to comment about the comments section, but you was faster 😃. A redundant comment could became a problem because with time people tend to update the code and forget to update the comments, so I would avoid comments on code and try to make the declarations more comprehensible as possible.

But @mahabubr, very good article anyway, congrats.

Mahabubur Rahman • Jun 16

thank you for share your prospective

Jon Randy 🎖️ • Jun 17 • Edited

Your 'Performance Optimization' example is wrong / nonsensical....

The 'Good' example runs slower than the bad example - therefore has worse performance
The 'Bad' example consistently runs faster (see benchmark here)
The two examples do different things (the good example does a numerical sort, whilst the bad example does a string sort) - rendering any performance comparison meaningless.

Michael Dawson • Jun 16

Great post! In my experience we need more people taking clean code seriously and helping raise the tide 😁

Often when I talk to people about these type of things I get responses like “I don’t care about writing beautiful code, we have real work to do”, so I feel like it’s always important to focus on why these principles are valuable. They help us build systems which can adapt to change more easily. I find that most of the value comes from just putting in a little effort with SRP and variable naming ✌️

Anthony • Jun 17

I don't agree with the magic numbers example. I don't understand how using a constant violates clean code principles. In your bad example, you use TAX_RATE. If the tax rate changed, you would have to go through your function and update it in multiple spots. In a large code base, there is the risk of missing a value.

I agree with the other devs regarding your comment examples. I personally only add comments to add clarity for a decision made that isn't easy to articulate in the code itself. The code itself would be written in a way that explains its function.

Diu Gach • Jun 18

Since taxrate is stored in a constant variable, that will only take a single change, change the taxRate variable to another value and that's all, my opinion though.

Paul Danger Kile • Jun 18 • Edited

Please change the name of this page to "Mastering Clean Code: Essential Practices for Javascript Developers". That would make it a more clear and descriptive name.

Maybe put the language version in the text at the top of the page. So instead of "JavaScript", it could say, "JavaScript (ECMAscript 2023)". That may help future readers understand the context, depending on future additions to the language.

Thank you for writing this, Mahabubur Rahman, and commenters.

TheNickest • Jun 15 • Edited

I personally like seeing developers applying clean code principles, so I hope my feedback finds you well. Your source code lacks some highlighting. Would be neat to see that next time.
Also error handling and asynchronous are not really consistent. The then/catch example appears to be ok for errors but not for asynchronous operations? It also hides the fact that there can be good reasons to choose one over the other. I agree that it can get messy if nested too much, but this is not shown in your example.

Mahabubur Rahman • Jun 16

thank you for share your prospective

Andy The Web Dev Queen • Jun 15

What a great post! Every developer should follow these instructions. Clean code is the best prerequisite for a great project.

Boby Tiwari • Jun 17

Thanks, now I know how to write clean code