How to: Improve your code legibility in 2 steps
“How can I make my code easier to read?”
This is a question we must ask ourselves if we want to improve the way we write code and in order to apply good practices, 2 of the many reasons why we have to worry about writing good code are:
- No matter the size of your team, big or small, you are creating code for the future, what do I mean? You are most likely not the only one adding code to the project. And it is better that it is an understandable code so that the onboarding process of the new members is shorter.
2. The time you spend “extra” in making your code more understandable is time that you will save later trying to understand what that piece of code does and explaining to others.
Your code it’s not going to be perfect in a productive environment, with tight deadlines, working with existing code sometimes cannot be made in the most efficient way, anyways there are some rules and practices we can adopt to make other developers life easier.
— — —
Unicorn Tip:
You can start by making your code readable. One of the initial steps that you can make is to create code standards and developers’ rules. You don’t need to change all your code at once, you can start by changing variable names, breaking up one function that’s a little large, eliminating unused variables.
— — —
Little Steps you can take in the way to improve your code are the following:
Naming
If after 2 weeks of naming a variable or function you can’t remember the meaning of it. You need to consider changing it to a meaningful name, easier to understand. The name should represent the type of the intention, the name should answer the 3 following questions:
- why it exist?
- what does it do?
- How it is used?
“If a name requires a comment, then the name does not reveal its intent.”
Check out this portion of code:
What makes this code kind of difficult to understand at first it’s not the complexity of itself, it’s the poor naming. The code itself doesn’t express what it does, how would I use the stack.
Let’s see a more significant naming definition:
- Avoid using abbreviations, even when the name It’s going to be a little bit long. For example: for Date dpay for dayPayment is an abbreviation of the name that makes the intention harder to get at first.
- Use pronounceable names to avoid using complex abbreviations like mdyPayt for something like timeStampPayment.
Comments
Try to explain yourself in your code, instead of writing tons of comments, Someone said to me once: “Code is like a book, you should write in a coherent, clean and elegant way”.
But in certain cases it is necessary to write some comments:
- Legal comments
- Informative comments.
- TODO comments
Some examples:
Use of regions
There are so many opinions about if the use of regions in your C# code, instead of being categoric, I’m going to give you some examples of uses and cautions you can take into consideration when using regions.
Do and Don’t:
You can use regions to standardize your code, in some companies, there are some rules about the naming or the structure of the classes.
An example of the use of regions:
In this example I am using regions to define the structure of the unit test to follow in all of them, this makes it easier to find and understand any part of my unit test for everyone. And guides to other developers of the structure are expected in the unit testing.
Again this is optional, the code is going to run with and without regions. Regions are prescribed with cautions:
- “Regions do not make your 800 or 8000 line classes any less awful and smelly than they would be in a language without regions.”
- Don’t use it for hiding large code blocks in regions instead of refactoring them and considering how their structure could be improved.
- Remember the SOLID principle of single responsibility: you should not divide a method using regions because your method does different things, if that’s the case, refactor your code to apply the principle.
This leads to an undeniable truth: make your methods short, concise and, following single responsibility principle make the maintenance easier and also leads to better testability.
Conclusions
- Clean code is a continuous journey that leads us to a better version of our code. In productive environments, it is hard to keep your code clean, but It’s not impossible.
- Code Review policies and developer’s rule is a must.
- Part of this information is based on the Clean code book, so I strongly recommend you Give it a try.
- These tips are the corner of the big picture on the way to make your code more clear and easy to understand but are not the only things you can do to achieve it, keep learning, keep coding and take care of yourself.
Bibliography:
Robert C. Martin. (2008). Clean code. Stoughton, Massachusetts: Pearson Education Inc.
