How many times did you work with a codebase which you did not write?
How many times you were working on a codebase and a newly hired developer did not able to work on the same codebase with you?! (and you’ve got that comment “who’s the hell did write that code?! and it was you…it’s the very annoying situation”)
Writing a nice readable clean code has no manual which you can follow. It’s just best practices and guidelines and here are some points I’ve faced while my career path which may help.
Functions and procedures:
Function names should be descriptive as you can understand what it’s doing even by reading its name. Function name should not belong and it’s preferred to start by a verb. For example, using the following function is a bad practice “check_valid_membership_data_for_user” you may use such name “validate_membership“.
If you’re working with classes do not use the class name within the names of your functions (function for sure it belongs to its class so no need to replicate such info).
For example, if you have a “User” class creating a function with the following name is a bad experience “get_user_payments” but the best name for such function is “get_payments” as you’ll use it as follows within your code “$user->get_payments“.
Camel-case or underscored! yeah, it’s one of the annoying experiences to have camel-case underscored mixed code. If you’re working within a team you’ve to agree on which type of naming conventions you need to work with. I’ve faced such a case lately while working with Peter. He suggested using underscores while naming our method and variables. At the first, I saw that it’s useless to do so (as I love the came-cased methods). After some point in time, I was reading a class in which we’ve applied such convention and then compared it with and old version of code. I smiled and said yup you were right Peter(he won the land this time :D).
The naming convention for variables and properties:
Well, who doesn’t use a variable in his code, the answer is no one but who is writing non-readable or even understandable variable names, then the answer is everyone. When you ask a developer why you did so he’ll surely say “Man I got stuck with a new release and had a very long backlog how come to care about a useless variable name. That may consume a lot of time” (actually I was one of those fools who do so). BTW it’s not useless to care about variable names and yup it deserves to invest a minute to think about a descriptive name. I’ve read some old articles that agreed if you’re working as an individual or a freelance developer it’s useless to care about naming conventions. I can see that it’s wrong. If you look back to see the old code you’ve written 2 months ago you’ll never remember why the hell you’ve written such a variable name. So it deserves taking a minute to think about it.
Managing dependencies:
One of the most things that annoy me is working with lots of dependencies within a project without having a dependency manager that handles such annoying tasks of updating and getting the chain of dependencies. For example: using bootstrap within your frontend code. If you’ve downloaded bootstrap manually you’ll end up downloading jquery too. And the later bootstrap versions cares about the minimum version of bootstrap. And here we go, we’ve to get the proper jquery version. That was a simple example. If you’re working with a complicated dependency that has a long chain of other dependencies this will be very annoying to care about each version. Using dependency managers like bower (in frontend) and composer (for backend) will help you to have free nightmares sleep.
Loops and control structures:
loops, if statements and loops and even more if statements, ugf I cannot read such code, who’s the asshole who wrote that shittttttt!. Lots of us faced such problem when reading not well-written code. Using loops and control structures is a mixed blessing. And to avoid being an asshole. You have to care not to have lots and lots of nested loops and control flow items within your code. Suppose having such code
foreach(............){
if(..................){
switch(......){
case 1:
foreach(.........){
}
break;
…..
}
}
}
This is a bad experience to have such a code. Having 3 nested indentations is enough to have a readable code. So please do not write that shitty eye-bleeding code that has lots and lots of nested blocks.
The previous notes are not rules that have to be followed when writing code, they’re just best practices I’ve come up with. You build up better rules for better code. Just set your own rules and follow them.