By Franck Brignoli – Core developer
There is an infinite amount of advice on the best way to write or organise your code. Here we deliver 3 key tips to keep in mind when starting your programming sessions.
1. Write explicit code
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." (Martin Fowler)
It is often said that code should be commented to help comprehension, but you should ask yourself why the code needs explaining in the first place.
Naming variables, classes and functions are key aspects of readable code. A good variable name is one that is descriptive, without abbreviations, but quite short.
For example, here are three ways to name a list of usernames for « shop »:
$shops: not great because we expect to find
$id_shops: better, but still not perfect.
$id_shop_list: this version can’t be confused with a
$id_shop, and shows explicitly that it is a list
Finding the perfect name can be really challenging, you should spend time thinking of one that is immediately easy to understand. Come back to it a few days later or ask someone else to read it to check if your code is solid.
When you’re writing code, you shouldn’t try to be wildly original or clever by using syntax that only you are able to understand. Use the comparison operators judiciously, for example.
Respect the project’s technical standards (if there are any, like with PrestaShop), and work at keeping a certain consistency with your naming, which will help with learning the API and so code more quickly.
Example of consistent approach in PrestaShop:
2. Create simple functions
A function should do one thing and do it well. This is a basic rule that will help you when you need to fix bugs, test and overload the function.
In general, we put a limit of a certain number of lines on the function size. If you go over this limit, it means that your function can be divided into several sub-functions.
Another advantage of having small and tightly focused functions is that it makes understanding them easier, and therefore means you won’t have to re-implement a function that already exists.
3. Maintain your code
The code of an application will always degrade over time, causing what developers call « software rot ». Code added over time, design errors caused by deadlines or the developer, and consequent patch up jobs are all inevitable. Your application will be increasingly difficult to maintain and build on.
As well, once a part of the application is contaminated, you probably won’t hesitate to mess it up further, saying to yourself that «in any case, I’m going to redo this part » and the software rot will continue to spread (see software entropy).
To put off the rot, you really need to maintain your code:
- by avoiding duplication as much as possible
- by taking the time to rename a few variables
- by redoing part of the code
If you have the time, at least comment the part that needs changing. But remember that it’s an essential and in-depth job that should be done every day.
A few reference books if you’re interested: