I’m supposed to be fixing a bug in my Expressionengine module right now. But, instead of that, I feel like procrastinating a little bit and write about fixing bugs. Not exactly just about fixing bugs, but a lot of other things about writing codes. But well, I think I didn’t mean to write about bugs, but since it’s been written this way, I will just leave it there. I will write about fixing bugs next time.
This time, I would like to write about writing. Writing is a very old technology. Writing is said to be the requirement of a civilization to success. And now, we have come to a point of time where writing is very important for every single person on Earth (I’m not really sure about other planets, though).
Holy crap, this is going to be a very boring article.
There are probably tons of articles on how to write English well. My question is, can we apply these human language principles in programming languages? why not?
Writing codes for computers has evolved from writing symbols that only computers can understand (or probably binary? I don’t know) to the variety of so many high level programming languages where it’s more for human to read rather than the machines. But the problem is, there is still a very big gap between what a computer can understand and what a human can read. And I have to say that it’s easier to write for the machine than for human to read.
My job for the past few weeks are basically reading codes. I would like to call my self a software archaeologist. Wait a moment, some other dude already used that term before? fine…
Reading people’s code is time consuming, stressful, difficult, and a very complicated job. Programmers love to complain about having to debug some buggy codes or being in the maintenance mode without being able to write new codes from scratch. But, let’s read it like a book. There are stories to unfold, mystery to solve. There are characters like functions, objects, variables, classes. the more we read, the more we understand them. The emotional connection between the readers and the fictional characters grown.
What if we write codes like we write books. What I mean here is that we take human as our main audience and focus on delivering information that are intended for human to read. That’s probably what we have been doing all this time by writing comments in our codes. But, writing comments are just part of the task here. I believe we can do much more than writing comments. We can even write to a point where we don’t really need to write any comment anymore.
Proper naming of your characters
A good writer doesn’t roll a thousand faced dice filled with human names and set their characters based on the names that show up. Most writer pick a name because it has something to do with the story. Darth Vader actually means Dark Father where he turn out to be (Spoiler alert!!) Luke’s fathers.
We name our everything in our codes. We are the god of that universe. But that universe is not yours alone. So, name them for the purpose of clarity. We want the readers to understand what a function does without having to rip open that function. In other word, generate_random_name() should generate a random name and kill_your_self() will actually kill your self.
I know it’s difficult sometimes to pick a proper name. But, at least think about the future human readers when you are naming them.
Human readable algorithm
Once you’ve got the naming right, it’s easier to write human readable algorithms.
if andy.isStupid: andy.go_to_school()
But, there are also some other things to consider. There are always more than one way to achieve a goal in coding. The kind of codes I would like to read are the ones that are easiest to read without compromising performance. At the end, speed is still the most important thing for your boss.
Spaces
Put a lot of them. Put a line break on every groups of codes. Make it clear that this chunk of codes are family while its neighbor down there is something else. Remember, you are writing for human to read, not the machine.
Consistency
Last, and the most important one IMHO, is make it consistent. Make every style in your codes mean something. If you like camelcase, use camelcase. I sometimes use camelsase and under_score for a different purpose. camelCase for variables and under_score for functions.
It’s never about right or wrong. It’s about trust. If camelCase means functions, and suddenly I see camelCase which is not a function, I lose that trust on you. I can’t trust you anymore and it makes the whole program harder to read.
Phelio Gnomi 