Common Coding Mistakes You Should Avoid

Making mistakes is human. However, a lot of the mistakes that developers make can be avoided. If you’re able to avoid the common mistakes in this article, you will be able to write better and cleaner code.

This will not only be beneficial to you but also to the other developers that have to take a look at your code. So you’re not just doing this for yourself—you’re also doing your team a huge favor.

Here are some of those common mistakes that you should avoid.

1. Too Many Things Going On in One Function

According to the single responsibility pattern, a function should only be responsible for doing one thing. And one thing only. I’ve seen way too many functions that fetch, process, and present data all in one function. It’s considered better programming to split this up. One function that fetches the data, one that processes it, and another one that presents the data.

The reason it is important to keep a function focused on a single concern is that it makes it more robust. Let’s say that in the foregoing example the data got fetched from an API. If there is a change to the API—for example, there is a new version—there is a greater danger that the processing code will break if it is part of the same function. This will most likely cause the presentation of the data to break as well.

2. Commented-Out Code

We’ve all seen entire blocks of code containing multiple functions being commented out. No one knows why it’s still there. And no one knows if that block of commented-out code is still relevant. Yet, no one deletes that block of code, which is what you should really do with it. The reason no one deletes this block of code is that everyone assumes that someone else might need it.

Just delete that piece of commented-out code. Even though the code is not in the latest revision, if someone has plans with it the code is still available in version control. But that’s just my two cents.

3. Non-Descriptive Naming of Variables

I wrote a post a while ago about some simple rules that you can follow to create good names for your variables. And I can’t emphasize enough how important good variable names are. Most of the time, you are not the only developer working on a project. Other developers need to understand your code as well.

As I stated in that post, choosing good names takes time, but it saves more time than it takes.

4. Magic Numbers and String

Coming from non-descriptive naming of variables, we go to the next item on this list, which is about not assigning values to a variable. This is also known as magic numbers or strings.

A definition by Wikipedia:

Magic numbers are unique values with unexplained meaning or multiple occurrences that can and should be replaced with named constants.

Let’s take a look at the following code snippet:

for ($i = 1; $i <= 52; $i++) {

The number 52 in this example is a magic number. No one understands why that number 52 is there and what it represents. And why is it 52? Why can’t it be 64? Are those the number of weeks in a year?

What’s way more clarifying is:

$cardDeckSize = 52;for ($i = 1; $i <= $cardDeckSize; $i++) {

Now everybody understands that we’re looping over all the cards in a deck. It gives context to other developers. On top of that, it’s much easier to change the value because it is not duplicated. It is stored in a variable only once.

Magic numbers are often used multiple times in different places within a program, which makes it error-prone.

The same can be said and done for strings:

if (userPasswordIsValid($user, "6yP4cZ".$password)) {

What is 6yP4cZ? It seems pretty random.

$salt = "6yP4cZ";if (userPasswordIsValid($user, $salt.$password)) {

Aha, now it makes sense!

5. Messy Formatting of Code

Messing up the formatting of code is something that is often done by people who don’t have a lot of programming experience. Most developers, with some years of experience, will probably nod their head if you ask them if they know a tester or data scientist who messed up the formatting of code. This comes from a lack of experience—unless they’re working with a programming language like Python, which saves you from a lot of this.

One of the most common ways to solve messy formatting is by using a linter. All modern IDEs also have the possibility to fix this for you. Sometimes you have to install a plugin, and sometimes it can be done out of the box.

6. Hard-Coding

Hard-coding is the software development practice of embedding data directly into the source code of a program or other executable objects, as opposed to obtaining the data from external sources or generating it at run-time.

Values that are hard-coded don’t allow for configuration; they are set in stone. Hard-coding is considered an anti-pattern or at least a very bad code smell.

Things that are being hard-coded the most, for whatever (sometimes maybe even valid) reason, are passwords and file locations.

A scenario where you see a lot of hard-coded passwords is for the authentication of an external service or API. Those credentials often get hard-coded, which isn’t considered best practice.

If you find yourself hard-coding a lot of things, you should really take a critical look at your code, because most of the time it isn’t the best way to solve a problem.

Leave a Reply

Your email address will not be published. Required fields are marked *