As the third part of my code refactoring blog series, I will discuss hacking code for readability. Check episode 1 and 2 to learn more about code refactoring.

A big reason why web stakeholders, including developers, have a really hard time working with existing code is due to the difficulty of deciphering what the code is doing, or to put it more broadly, the lack of documentation. Although fixing this problem does not contribute to any new enhancements, features, or bug fixes directly, it affects the project in more ways than a stakeholder might envision.

But wasn’t documentation something that is included in the site build?

Reasons for the software to lack documentation can vary depending on the relationship between the clients and the developers. However, some of the more obvious reasons include:

• It was not explicitly included in the contract or was not elaborated in the agreement in detail

• Some developers might cut corners to meet an aggressive deadline

• Requirements continually change for various reasons, causing documentation work to become useless.

So why does it matter if it’s not well documented for the clients or for other developers who might be maintaining the code in the future? After all, it ultimately:

• Does not impact the functionality of the code

• No one is going to read it

• It will increase the budget on the project

• The client does not care what is going on in the code

• Once this project is done, “I doubt we’ll need changes for a long time,” therefore, let this software run for the next several months

Although all these claims have some validity, there are reasons why documentation is a critical part of a project. It can provide huge value to both the developers and the clients in different ways. However, before I proceed, it’s important to distinguish the type of documentation we’re dealing with here.

End User Documentation

This is typically the stuff the users of the system will read to figure out how to use the software. It could be in a form of a user manual or textual tool tips associated with widgets on an application. Ideally, if it helps the user figure out what to do without additional assistance, then it’s been implemented effectively.

I stress requiring additional assistance because it saves time and resources. Let’s say you develop a product that serves consumers with a variety of services. However, if the consumer constantly needs help using the system, they will most likely contact the client for help. Whether this form of assistance is in a form of a call center or a ticketing system, it increases the size of a support department that may constantly service remedial requests, costing the client time and money.

It is important to recognize that providing documentation in this fashion may require a large investment. However, depending on the volume of users, it will save the client a large sum of resources in the end.

Code Documentation

Documentation can be embedded in code. We commonly refer to them as comments in most languages. Every system has their own mechanics for allowing developers to explain how a snippet of procedures work, why it was put there, and how to configure it to cater to specific needs. Good developers make use of this feature, sometimes over documents (it is not uncommon to see more human language than code in many scripts in a piece of software) for the following reasons:

• Reminds them of what the script does in case they have to deal with the code six months later, when most might forget the purpose of the script

• To communicate with team members more efficiently on what the code does to assist them in their troubleshooting or to expand on the functionality

• Notes (typically in a form of @TODO) to remember why something was done in a certain way and directs them to either fix the implementation or remove it in the future.

In a way, it is correct to say that documentation in code is a way to effectively communicate with other developers or future contractors without having the guys working on the code actually talk to each other. It saves time due to overhead from meetings, office chats, and sometimes working with each other to ramp up the developer who doesn’t have much experience with the code (this is only if they’re lucky the developer is still around.  In some cases, they may not be available).

In a sense, this does add some time to the project, but when it becomes good habit, it barely takes up that much additional time at all unless it’s complex and requires more elaboration. Something as simple as…

/**
* Adds two numbers together
*/
function some_really_complex_function(x, y) {
 return x + y;
}
some_really_complex_function(1,2);  // 3

Now imagine if there was hundreds of lines of code in the first function. Most will spend a lot of time trying to figure out what the function does. However, if you read the first part (the English part), you might save yourself a ton of time because it summarizes the large function in a few words, allowing you to skip it or review it depending on what you’re doing (troubleshooting or feature enhancements).

This is critical to developers who may think differently from each other. There is no one right way to implement a feature, developers who think differently from each other approach a problem and solution differently, and in the end both approaches work. It’s sort of like speaking a different dialect, two people who differ may say the same thing but in a different way. Good documentation also comes in handy here because it bridges gaps between different coding styles. This could potentially prevent one person from deciding to refactor other people’s working code, which then yields wasted efforts.

Getting in a good habit of good code documentation not only saves developers a lot of time, it also saves stakeholders resources,(whether it is time or money) as well. Future maintenance will be greatly cheaper and it yields a lot more time to work on new features on the site (after all, most people hate the idea of losing their investments on bug fixes rather than new additions to their software).

Nomenclature may make code bearable too.

Suppose we have a genius developer who creates great products. However, no one can read his code because the syntax doesn’t make sense.

function atnttmas(x,y) {
 return x + y;
}
atnttmas(1,2); // 3

Again, imagine this function had hundreds of lines of code, and (for the purpose of this exercise) he also doesn’t document anything he writes either. Therefore, ask anyone on the street what atnttmas means, and they won’t have a clue. However, since we all speak similar languages, if he instead renamed his functions like this:

function adding_two_numbers_together_to_make_a_sum(num1, num2) {
 return num1 + num2;
}
adding_two_numbers_together_to_make_a_sum(1,2); // 3

It would clear a lot of confusion. As a side note, we would realistically rename this function to addition() and it would send the same message.

To contact the original developer to figure out what he wrote, to try to decipher what he wrote, and to constantly look through the code for any references to this function just to figure out what it does is time wasted for both the developer and the client. Therefore, it helps to rename these things to save a boatload of time (sometimes even if it is well documented in other ways).

Thinking like a Librarian and Organizing Your Code For Better Searchability

It’s also beneficial to have a good organization schema for the code as well. When you have a piece of software that has a large script with thousands of lines of code, it makes sense to split it up into smaller more manageable chunks.

• Splitting into an understandable schema creates easier findability

• You won’t have conflicts when more than one developer tries to interact with the same script (especially when it comes to older version control software like CVS and SVN

• There’s a lesser chance of the entire script getting corrupted.  If one small bit gets destroyed, it’ll be easier to troubleshoot that

This route may not be easy depending on how the code is set up. However, most languages today, especially ones like C++ and Java that operate using an object-oriented methodology, make it easy to split up code into smaller bits. Therefore, there is no excuse. It also makes reviewing the code less intimidating (especially, when organized well.) It helps you ignore much of the code to prioritize other specific parts.

How can this be done?  It depends on what level you need to organize.  For example, you can organize code based on:

• Custom in-house code and community or third party software

• Database interactions, front end design, and scripts to pull the two layers together (very common in MVC models)

• Main code and help functions that can be used many times

• Code, image assets, downloadable media, and content

Again, it’ll make it easier to work with the code. However, the additional value this brings to all stakeholders is the power to migrate functionality and content in the event you want to bring the software to a new platform. Having things jumbled together without an organization schema not only takes longer to migrate but is also prone to errors (like forgetting a piece of content or functionality).

So what value does all this bring again?

This aspect of the project often gets ignored mostly because it risks the project yielding little new features over an extended period of time. It also does not make sense to document something that works that no one may interact with again.

Therefore, the best way to approach this is when you, as the developer, have a task to interact with a piece of the code. If it is deemed difficult to work with the piece of code due to lack of documentation, this is your chance to fix it and write notes so that if you or someone else has to deal with it, it won’t take as much time as the first time. This might extend the estimate by a larger margin, but, for the long term, it saves a lot of time and resources.

Find my whole refactoring series here!

Code Refactoring- An Explanation In Layman’s Terms

Code Refactoring- Changes For Biggest Bang For Your Buck

Code Refactoring- Hacking Your Code For Readability (you just read this)