If you are a professional web developer, it’s likely that at some point you’ve had to maintain a block of code or script written by another developer. Did you spend hours try to deduce the purpose? Was your initial response, “this is crazy?” If you’ve ever heard another team member’s name used as a verb or adjective in describing bad code–and you don’t want to be that person at some point–you already understand the importance of writing clean code.
As a developer, you are not only responsible for the result of your code, but also the integrity of the underlying components. It is possible (and often faster) to create a block of code that meets the goal, but which is otherwise unintelligible.
Meeting deadlines with bad code works–that is, until you or another developer has to return to the stew of code to update it or correct an error. While creating code that is clean and readable does add a bit of time and consideration on the front end, the benefits will definitely save you time later down the road. Here are some simple things to keep in mind when you’re hammering out your next theme or plugin.
Focus and Intent
When you’re clear in your own mind about what you are developing and why, it can go a long way toward helping you organize and maintain clean code. Try organizing large pieces of code that serve many functions into smaller chunks that are easier to understand and maintain. Smaller logical chunks that can function independently of one another will narrow the margin for errors versus one large interlocking document.
To illustrate, think about an automobile. A car is one large machine made up of separate systems working together to operate the whole. If you were writing an application that mimicked a car, you could theoretically put every line of code into a single file and a single function named “car,” but this approach doesn’t consider that a car consists of an engine, transmission, wheels, headlights, etc.
Should you ever need to work on the engine, you wouldn’t be working on the transmission at the same time, so it would be ludicrous and confusing to have a file named car.php inside which was a function named car() that described every operation the car performed (engine, transmission, wheels, headlights, and so on).
A much better approach would be to break down the car function into smaller more focused functions such as engine(), headlights(), or wheels(). To further organize car.php, you could move focused functions into separate files: engine.php, headlights.php, etc. In the end, you’d have smaller chunks of code whose intent is more immediately clear. You wouldn’t have to dig through the entire car to just fix the wheels.
Clarity and Self-Documenting Code
I have heard many developers defend their sloppy illegible code by claiming that they can save time by limiting the number of characters they type. Such time-saving measures come in the form of vague one or two letter variable names, function names that do not communicate their purpose, or a complete absence of comments. The code was likely understood by the developer when it was written, but no one else is going to have any context for it. When it comes time to revise or refactor this code a week or a month later, someone’s going to have to untangle the mess. So much for saving time.
Because variables and functions can be declared many lines or files away from where they are used, vague names for these variables and functions can (and will) lose context if they do not describe their purpose–so when writing a function or variable name, try using descriptive text to keep it in context. A function named “myFunction” only communicates that you (or someone else) wrote a function.
By contrast, “myFunctionThatAddsTwoNumbers” is a function name that explains what it does. Without digging any further into the code, you know that the function will add two numbers. This extends to variables as well; if you were saving the latitude of the Eiffel Tower to a variable, a good name would be something like “latitudeOfTheEiffelTower”. or something similar to describe what the variable contains.
Another way to improve clarity in your code is to document it directly using comments. Complex code with great self-documenting naming can still be difficult to read and understand, so even a small comment can go a long way to helping other developers understand. If code consists of nested conditional statements or loops, familiarity with the programming language won’t always be enough deduce the solution applied to the problem.
A short comment to explain when a statement ends, or to describe how one part relates to another, can go a long way toward guiding others through your code is important. Think of it as writing it down so you don’t have to explain yourself later.
Coding Standards
If you’re having trouble figuring out how to clean up your code, or if you’re having a semantic argument about formatting with a co-worker, there may be some documented coding standards available depending on the technology you’re using. WordPress, for example, has guidelines for HTML, PHP, CSS, and Javascript.
Completely integrating or including the coding standards from technologies like WordPress not only cleans up the code you are writing but also aligns it with the standards of the community–a community that you may be asking for help, hiring from, or working in. Keeping things clean and consistent with any current coding standards helps you understand one another.
A Cleaner Future
If you found yourself guilty of any of the sloppy code-writing described above, I’d encourage you to use some of the suggestions above as a starting point for cleaning up your code. It will require some effort and a small investment of time, but in doing so, you’ll not only gain more pride in your work, but you’ll save yourself and others a lot of time and headaches later on. For even more helpful information, you might look at the book Clean Code: A Handbook of Agile Software Craftsmanship for further reading.
Leave a Reply