Although we already use PHP Framework, there is a possibility when our code is confusing enough and sometimes the original code author loses context why they even code like that because many of us wrote custom business logic which often changes every time.
These tips is quite general and can be applicable to many programming languages but this time we will cover it to PHP.
Although the machine doesn't seem to care about our variable name, don't forget we also wrote code for humans. Writing meaningful names for our classes, functions or properties can help other developers (or even yourself) to understand your code quickly.
Imagine you wrote a code like this
Yes it might work, but this may got some questions
what's the purpose of
We know we can pass two strings to
domethod, but what data?
We can write more clear context about this class with something like this
It's all clear about each property's purposes and what data need to be passed to the function and also we can know this function is to handle login action.
Avoid Magic Values
Magic value is a value that exists without knowing what the context of the value is. It often showed up in conditions, something like this
If you wrote this code probably you understand what the context or real meaning of value
10000 . Another developer will be hard to understand especially if there is a change needed and related to this function. They will have no clue what this number means.
Simple constants will add reveal more understandable meanings from these values
Aah, so we understand now that
1 is a flag for the user's active status and
10000 is a minimum balance that needs to be checked with the current user's balance amount. Even better, we can add more clarity to this condition by extracting it to a different method.
It's more clear now the condition is to check if a user is allowed to withdraw their balance or not by checking those attributes.
Avoiding magic values will benefit you in the long term because it will easier for any developer to grasp what's the code do.
Try to Prevent Nested Condition
It's a common thing that every time we code, we are adding conditions to handle different things in one function. You may familiar with this coding style
Actually, there is nothing wrong with this code. It will give a valid output when we run it. But the nested condition is one of the code smell symptoms that we can avoid. If our function output is returning something then we can use the "return early" method. Something like this
Finally, we can remove unnecessary
else condition blocks and make our code more simple and readable. I mean, it is less cluttered, right?
Do We Need Comments
The code should be self-explanatory. If we implement better naming and avoid magic values, it should minimize our need to add comments. Only use comments to add something necessary, such as:
Trade-off explanation why function needs to be executed as a certain rule
What point or process needs to be aware
Remove Dead Codes
Sometimes during development, we "commented" some piece of code to disable certain processes. This is fine, but when we need to release the code or push it to the main / master branch we should delete any remaining dead code.
Dead code can be confusing in the future because it's like a state between "do I need it later or it's completely useless?". Another developer will be more confused because they don't know the main reason why it commented.
What if I need to put the codes back in the future?
No, mostly you don't. It should be clear before we push it to the main branch. However, that's why we also use version control. So we can check the code histories.
I also have a deck covering some of clean code principle that you can here.
So what's your favorite technique to make your code more readable? Let me know in the comments.