Code Like a Professional
Your code tells a lot about the type of programmer you are. The structure of your code, the arrangement, and the naming methodology you use are most times an indication of the programmer behind such code.
You’re the author of your code and you have the right to dress it how you like. However, if you want your code to represent you properly and present you as the professional that you are, there are some best practices you can follow to achieve that. You will still have the autonomy to dictate how the code will look and work, just guided by a better practice.
These best practices will help you achieve a good clean code.
What is a good clean code?, Why do I need to write a good clean code?, How do I write a good clean code?
These are the questions I aim to answer in this article. I will provide answers to them in reverse order starting with the latter question.
1. How do I write a good clean code?
Writing a good clean code is quite intuitive. I have highlighted a few characteristics that I have used and learned in my short experience. I have listed them in no chronological order.
Naming
You have likely faced some troubles when naming something in your code, I have. Sometimes, the names will come at you in seconds, other times, it may be difficult to come up with one. These are the times we resort to names like tmp, haha. It’s true.
When the problem of naming comes up again, you can use these tips.
- Choose a word with meaning (it should relate to what it addresses)
- You can use multiple words e.g. firstName or infoHub or getTransactionHistory
- Remember to be consistent in your namings
Good naming improves the readability of your code. It makes it easy for others to read your code well and even helps your future self understand your code.
Here’s an article on naming that might help: https://medium.com/swlh/how-to-better-name-your-functions-and-variables-e962a4ef335b
Comments
Commenting involves placing human-readable descriptions in your code detailing what your code does. You can put as many comments as you wish.
“Proper use of comments can make code maintenance much easier, as well as help make finding bugs faster.” ~ cs Utah
Just like proper naming, comments make it easy for guests to read your code and understand your line of thought. It is especially good to include comments in the source code you are writing that others will use or interact with.
Here’s an article on commenting best practices: https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html#:~:text=Commenting%20involves%20placing%20Human%20Readable,that%20other%20people%20will%20use.
Documentation
This is very similar to comments. However, it takes a step further, you don’t write documentation in line with your code as you do comments.
I refer to documentation as a biography of one’s code. This is where you talk about your code. It is a narrative about your code that details your thought process, the implementation and know-how of the code.
Well-written and maintained documentation explains the specific features of a project, informs the audience on how they can work with the project and helps them to understand the project’s functionalities.
Some might say that documentation is only required if you’re working on a project that others will use. Well, as true as this can be, I will argue that you should at least have a detailed README file in all your projects. As I have previously highlighted, well-documented code is as important as correctly working code. You can never go wrong with well-detailed documentation.
Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?” Improve the code and then document it to make it even clearer.
-Steve McConnell
These are two articles I have found to be well-detailed documentation on the topic of Documentation.
- https://www.hongkiat.com/blog/why-documentation-essential/
- https://maddevs.io/customer-university/importance-of-documentation/
Write Tests
Oh, the sweetest bit. You must write tests. It is very important and crucial to any project you are working on. Tests make your code clean, flexible and maintainable.
When working on a project, you know what you want to do, write tests for that and it will probably fail because you haven’t written the code to make it work. So your task then becomes writing the code to make the failing test pass.
This process is called Test Driven Development (TDD) in which requirements are turned into specific test cases then the software is improved to pass these tests.
Use OOP (when you can)
This might require an intermediate level of programming to use properly. Also, note that this is best used on large projects.
OOP is Object-Oriented Programming. It is a computer programming model that organizes software design around data, or objects, rather than functions and logic.
OOP can make your code modular, scalable, maintainable, extensible and reusable.
This is a huge topic and a crucial one. If you can add it to your toolkit, it will make you an even better programmer. So here are a couple of articles you can look at on the importance of OOP and when to use it.
2. Why do I need to write a good clean code?
Wow, you made it this far. Well since you got here, you should be able to answer this question yourself. Why do you need to write a good clean code?
I say you don’t write a good clean code for your present self, you write it for your future self and other people that may look at your code.
Have you ever been in a frenzy of writing a code? You get all these ideas that you just type it all out, unstructured, scattered, anyhow but it works. But when you come back to that code in 3–6 months you ask yourself, why did I write this function? What does this method return? Where is this variable used?
Yeah, I bet you’ve been there. So simple answer to our favourite question, “why do I need to write a good clean code?”, is you write a GOOD CLEAN code to prevent you from asking those hilarious questions the next time you look at your code after some time off and to help others have a good read of your code.
3. What is a good clean code?
You can answer this one too. What is a good clean code?
A good clean code should be self-documenting. It should be able to communicate, at first glance, what it does.
Now you know how to make yourself a better programmer. Let your code tell a good narrative about you!
Happ coding!
