I never write bad code. My code is always readable, perfectly modular, standard following, understandable, completely commented and idiomatic with 100% code coverage unit tests.

Ok. You can stop laughing now. Really, stop laughing.

As software folks, we will always bias that our code  easier to understand than that written by someone else.

Of course it is. You wrote it.

We get used to our own style, habits and ways of thinking about software implementation. It’s natural.

However, when it’s crunch time and the the deadline is now or our motivation is less than stellar, we have all written code, that, upon later reflection, is not much better than rotten barnyard material. Sometimes we write code that way during times of less stress and pressure too.

When you write code like that for a business, realize that someone will come after you. And the person who comes after you will have to fix bugs, add features, migrate to new environments and any other number of interactions with your code.

What will that person find?

If you want to pay it forward as a developer (and I am requesting you do), here are six simple ways to be kind to those who will work on your code after you are long gone.

0. Document block your files, classes, and methods

State your assumptions, purposes, reasons, pre-conditions, dependencies. Tell those coming after you what will help them understand not just what you did but why you did it.

Sometimes it can seem redundant (especially if your code is as good as mine) but a good doc block can clarify a class’ purpose or the reason a method is implemented the way it is. Plus a good doc block can be the high level overview that makes reading and understanding the actual code go much faster.

Doc blocks are a super help to the software archeologists that come after you and try to add features or refactor your code for some other reason.

1. Comment your code inline

Really? Are you kidding me?

I am astounded that with all the “software education” and common best practices we have access to, professional (?) developers still neglect to add relevant comments to their code.

I recently went through a file that was several thousand lines (yeah, I know) and there were no comments. We were trying to re-factor a bit of old code to perform correctly in PHP7. In a particularly obfuscated section of code I found myself asking “why did you do that?”, over and over again.

A simple line or 2 of comment in a method or variable definition can  prevent the person coming after looking at the commit log and cursing your name and yelling “What were you thinking?” And, if by chance, you happen to come after yourself a year or two later, a comment will help you remember why you set:

$Contibulator_Fudge_Factor_Ratio = 4.26;

2. Mind the coding style

You will annoy those who follow you by randomly changing coding styles. Tabs or Spaces? Braces on the line or under the line? Camel case or underscore separated names? Whatever you choose, do it the same way.

Consistency means those after you only have to figure out something once. This is especially true if you are adding code to a system that you didn’t write either.

3. Maintain architectural intent

When you code, have consistency in your implementation. There are few things more disorienting than trying to figure out why a previous developer had 3 ways of doing things.

When you need to talk to the database, do it the same way each time.

If you are coding an MVC app, be consistent on your division of work. If you use a template in one view, use them in all your views. If you start with ‘thin’ controllers, keep it going.

If the data representation is JSON, use it consistently. Don’t throw in some XML here or there just to mix it up.

If you have a ‘js’ folder with your site javascript files, don’t all of a sudden start creating template files with 400 lines of embedded javascript (without a comment).

Finally, if, for some reason, you have to do something that is a deviation of the architectural direction – add a comment!!!! Tell us why.

Consistency in your implementation will also help speed any future re-factoring efforts that you or some other developer may be tasked with.

4. Communicate with variable names

Variable names like $x, ‘res’, ‘m1’, ‘ary’ and similar communicate nothing to a reader about intent or purpose. Outside of idiomatic usage, say, as a loop counter in a C language for loop (for i=0; i< 10; i++), these types of variable names scattered throughout a code base only serve to obscure and confuse.

If you have a display mode setting string variable don’t call it $dm. Call it $display_mode_setting. If you have a post count variable don’t call it ‘pc’. Call it ‘post_count’. If you have an array of customers that are expiring their trial usage call it $customers_with_trial_expiring_list[].

You get the idea.

Simply use the context of the variable usage to name it accordingly. Think about telling the developer after you something by virtue of the name of the variable. In this manner, any later developer who sees these can more immediately grasp its purpose.

5. Guide with commit comments

So you’re assigned a bug to correct a situation where a NULL file pointer is accessed causing an exception. You realize there were several commits to this file and check the previous commits against that code. You notice that there used to be a NULL check but it was removed in a commit 4 months ago by a developer who is no longer working at your company, and they didn’t put a comment in the commit. Now you are left wondering if that guy a compete moron or was there some other unknown reason the change was made. Maybe it was unintentional but maybe not. Without the comment you have no idea why. You simply soldier on wondering.

This situation can be improved with a simple commit comment.

Something like “Remove the NULL check here, the IO library group will handle it”.  This communicates a whole new level of information regarding the change. It gives you a clue on where else to investigate to make sure your solution is correct and complete and it only takes 15 seconds. Yeah it’s a bit contrived but it illustrates my point.

Good commit logs help those after you unravel the history of the code changes more effectively. Log those commits.

Conclusion

I know, these are coding 101 items. The sum total of time it takes to code this way is only slightly longer that without it. Even so, it is disappointing to see how often these simple actions are ignored.

And, as someone with the responsibility to maintain a fair amount of previously developed code, the lack of these 6 things makes me want to pull my hair out. I know you feel that way too.

I like the way Brandon Savage says it in his book “Mastering Object Oriented PHP“. He was admonished by a previous manager to:

“write code as though the developer coming after me would be a psychotic murderous maniac who had my address”

Humorous, yes. But it contains a great truth about helping those who come after you.

Let’s face it, without a Vulcan mind meld, it is impossible to be on the same wavelength as the original author of code you might be  working on. But with a small amount of effort you can lessen the frustration those who follow after you and even become a code hero in their eyes. And who knows, the frustration level you lessen may be your own.