It might sound cheesy, but actually, the title of this article is inspired by the movie "Fantastic Beasts and Where to Find Them". However, the article by itself is inspired by the book "Clean Code: A Handbook of Agile Software Craftsmanship" by the one and only Robert C. Martin a.k.a. Uncle Bob.

If you have been coding for few years, you would have encountered bad code at least once in your lifetime. Missing it is hard. Even if you are a developer, who does his 9-to-5 work only, and has not been trying to improve yourself continuously. After a few years, you would pick up on some patterns of bad and smelly code, because you most likely faced the consequences before, and knows what works and what not.

However, like most of the experiences in life, you don't have to go through them by yourself to know that they should be avoided. We learn from the history, or at least that's what they say. Now, even though the software engineering industry is not as old as other sectors, it reached a mature level that we confidently would know what works and what not. Plenty of books are written about bad and good code, and most of them are coming from experience.

What will be covered?

As mentioned at the top of this article, this series of posts is highly influenced by Clean Code, which, in my opinion, should be on every programmer's bookshelf. I won't be covering every aspect of it because that's not my intention, but instead, I will try to summarize some of the best practices of writing good code mentioned in the book but with a different set and with my examples.

What drives good code?

Good Code

Apparently, it is the developer. Now, some tools might help, like smart IDEs, and code coverage tools when unit testing to name few, but the majority relies upon the developer.

Mistakenly, one might think that clean code is being written from the beginning of a project; from day one. Say, we write clean code along the way following the best practices and finish up with a decent functioning system. Apparently, that's hardly the case unless you have decades of experience in writing clean code. Even with that, I wouldn't be so sure. Writing clean code is a repetitive set of work, yet as one is gradually implying the steps, they become a second nature and detectable at the early stage of the code.
The only similarity between bad and good code is that both function. Thus, some developers would write code that would work and stop there, but good code is being written by reevaluating it over and over.

Sometimes bad code is being written knowingly. For instance, a bad algorithm has been placed as a hack, or the deadline is approaching, and the team needs to ship a feature as quickly as possible to the customer. But the least one can do is set a note to self, or fellow developers to rewrite that smelly piece of code acknowledging the reason behind it.

Names

Naming

Naming conventions

Although the first chapter of the "Clean Code" is about naming; called "Meaningful Names," it is hard to start any good code without a proper naming habit when dealing with variables, functions, and classes.

A naming convention is important, and each programming language, organization, team, or project has its own. For instance, you can find python's naming convention in PEP 8. However, that is not what the most important thing about naming. Why is that? Because not following those naming rules will result in rejecting the code all together in most of the organizations nowadays. The code won't make it to the production if the reviewer spot that it is not following the rules. I have even seen it in some open source projects. Saying all of that, the naming convention is not what this is about.

Informative names

It's about informative naming when the variable, function, or class name reveal information about itself. This is what matters the most because we tend to spend more time reading code than actually writing it. A good function name could save more time than reading the implementation.

However, a disinformative name could be more of a problem than a poorly named function and should be avoided alongside with the single-letter naming. Let's take some examples.

n = 0 //number of items in the shopping cart

Apparently, n stands for "number of items in the shopping cart" according to the comment. That's an indication of a poorly named variable, especially when we have to scroll all the way to the definition of n to know what it stands for from the comment. Not mentioning that commenting the code in this way considered bad as well. I'm sure that number_of_items would make a better name, which is more informative, indicates what the variable stands for, and easy to search for it.

def get_products_list():

    ...
    return {
        'products': products,
        ...
    }

Because I implied the word list in the function name, I would expect a list back and not a dictionary that contains the products. This is disinformative because the word list represents a data structure in python.

Classes, and Methods naming

Classes should be nouns or contain nouns in their names like Product, ShoppingCart, Customer and so on. Methods, on the other hand, should start with a verb such as get_product_name() and save_order(). Those verbs should be one per concept. For instance, the following verbs: save, insert, and create tend to serve the same purpose for saving data. Picking one of them, and distributing it to the rest of the classes should be the case.

Domain names

The rule here is to use the solution domain names when possible. Otherwise, the problem domain names should be employed. The solution domain names are the computer science terms that the programmers are familiar with such as algorithms, design patterns, and math terms. Whereas, the problem domain names are derived from the problem that needs to be solved.

Conclusion

As shown, naming plays a significant role in the clearness of our code, and by following some simple steps, we do other developers alongside ourselves a huge favor when getting back to it months later.