Writing code is very easy. Writing good code is easy. Writing readable code is hard.
Coding is like writing a letter to your future self. If you can not understand when you read in future, you failed at initial writing! If not you, someone else has to read and maintain that code. Nonetheless, wherever you go, you will have to maintain someone else code. So the only choice you have is play a good coder.
If everyone does the job well, they serve community and indirectly they serve themselves.
I will keep the article short and to the point. Let me present you 3 most important aspects of code:
What
Why
How
The code written with ‘what mindset’ feels like a conversation with a machine. You give commands and get result. On the other hand code written with ‘how mindset’ sucks all blood sugar from your body. It is very confusing to read and hard to grasp. Let us go through a small example.
How Mindset
showUserPage(){
progressDialog = new ProgressDialog();
progressDialog.show(“Please wait”);
List<User> users = new ArrayList();
// fetching from web server
// parsing json
// looping json and filling users
for(User user: users){
// converting user object to UI objects
// showing UI
}
progressDialog.hide();
}
What Mindset
showUserPage(){
showProgess();
List<User> users = fetchUsers();
showUsers(users);
hideProgress();
}
If you read both of methods above, how-mindset snippet pinches in eyes and emits 5 volt electricity in brain. Though the latter one is music to eyes (Yes we have such thing in software :P ). Keep in mind above mentioned example is very simple and in real life we face way complex problems. I hope you get the point.
Readability is not the only one benefit of what-mindset over how-mindset. In above example, how-mindset explains too much. It exposes that users are coming from web-server and there is one Json which we need to parse and convert that to Users. Then we need to convert User object to UI object model and hide progressBar. On the other hand, what-mindset focuses on very least information which is needed. You do not care where users are coming from, thus it becomes easy to modify fetchUsers() and introduce a caching layer. You could add validationLayer, errorHandling and so on. You do not know data structure under the hood and you can not make any assumption while writing code. One of worst thing is assumptions while writing code with too much information of other modules. In other words, Loose-Coupling and Highly-Cohesive. If you follow these basic principles, you are golden.
Why a piece of code was written in such a way is mystery unless you unfold it along with codebase. Yes, I am talking about comments in code. Few coders are against comments and few are in favour. I am pro comments.
Writing comments does not mean explaining what of codebase. In that case, you failed at first point. Remember What-mindset vs How-mindset. I have seen codebase written with how-mindset and comments trying to explain what is happening. Like this one:
showUserPage(){
progressDialog = new ProgressDialog();
progressDialog.show(“Please wait”);
List<User> users = new ArrayList();
// now we are fetching data from web server
Json json = Webserver.post(“http://ShittyWayOfWritingUrlInCode.com/users”);
// parsing json and handling error if return code is 101
// looping json and filling users
for(User user: users){
// converting user object to UI objects
// showing UI
}
progressDialog.hide();
}
Above codebase is how-mindset code covered with why aspect using comments and justifying to everyone that it is inclined to what-mindset. In reality it is spaghetti or it will become one as project grows.
So always aim for what code is doing and write ‘why’ whenever you make some decision which does not fit under umbrella of what. Lets see one example.
Without-Why
fetchUsers() {
if(lastFetchTime is more than 10 seconds) {
users = webserver.getUsers();
}
With-Why
fetchUsers() {
// this 10 is not a magical number, Server needs delay of 10 seconds else we will get same result
if(lastFetchTime is more than 10 seconds) {
users = webserver.getUsers();
}
}
// NOTE : 10 will be constant :P
Do you see how much valuable that small information is. When you visit your code in future, you do not need to crawl through pages of documentation OR call ex-employees. You won’t frustrate yourself and delete the 10. Though you wont see any change in your output, you will waste user bandwidth and send more load to server, costing ton of money.
Remember, everything present in codebase was done for a reason. Good and bad code both. Only difference is it seems senseless without proper comments — the Why.
Why with Git
I assume you use Git for source management. If you do not, believe me you must. Whatever code source management you use, it makes sense to write your why in commit message as well. Though how to write a good commit message is out of scope of this article. Keep in mind, why in codebase helps you understand a unit of code. Why of commit message helps you understand bigger picture, why the change was made. They both have a separate place and their own importance.
To summarise, You should aim for readability over performance because machines are really powerful and way smarter than you can imagine. Computation is cheap. Manpower is not. Happiness is a myth :P
So my dear friend, always write code with What-mindset explaining why of critical blocks with a why commit message. Remember, hell is already filled with coders with how-mindset.
Happy coding.
