Articles, Updates

Writing Better Web Code

December 3, 2018 • By

There’s nothing quite like perfectly crafted code. People used to take pride in their work, but more and more frequently there’s a trend toward using cookie cutter solutions. While that can be helpful, it should not be the cornerstone upon which all sites are built.

If we do just keep relying on quick fix solutions where we don’t put in any effort ourselves and where most of the coding is done by third parties, there are problems that could arise:

  1. There will be too many sites that all look pretty much the same.
  2. Nobody will properly understand how their own websites actually work.
  3. It will be easier for people to slip malicious code into the components you use to construct your site, and you’ll probably never know.

Clearly the third problem is the most serious. Even if you’re using third party solutions as components to construct your website, there’s no excuse not to improve them if they can be improved. This is where understanding how to write better web code can help you gain more control and mastery over the inner workings of your site, and it’s actually a lot easier than you’d probably expect.

There are only five things we need to pay attention to. They are:

  1. Utility
  2. Efficiency
  3. Legibility
  4. Re-usability
  5. Future-proofing

If you want to be the best at what you do, master these four traits of coding and you’ll be well on your way to greatness.

1. Utility

When it comes to coding, utility means that a section of code actually achieves the purpose that it was written for. It must also achieve that purpose correctly and consistently.

As a coder, you think about the problem in hand, and think about the best way to solve that problem. If there is a third party solution available, and it achieves the desired result very well, then you could consider using it.

If it doesn’t achieve the result you want perfectly, you should consider writing your own version of it or modifying the source until it actually does suit your needs perfectly. Just make sure you comply with licensing terms.

That’s actually one of the best reasons to write your own code entirely. Then you never have to worry about software licenses and accidental copyright violations.

illustration by 

2. Efficiency

This is where many of those third party solutions really unravel, because not everyone who makes them is a genius coder. In fact sometimes they’re just cobbled together from a variety of other projects, creating a Frankenstein’s Monster of code that may get the job done, but not in the best way.

The greatest complication that arises from patchwork coding which draws from third party sources is the tendency to have those same third party resources following a complex chain of inter-related dependencies. If any link anywhere along that chain becomes unavailable, it can cause the technology on your site to fail. This is not mere speculation, it’s something that has already happened, and can be expected to happen again.

Duplicating the utility by writing your own code in the most efficient way is the simple way to eliminate the flaws that arise through the use of third party code. When you write the code yourself, you’ll be attempting to make it simpler.

Don’t over-complicate things however. Efficiency is not worth the effort if it makes your code more difficult to maintain and debug.

One simple way to improve efficiency is to move all computation blocks (anything that does something) into functions, and just use the main body of the program or script to call the functions in the proper order.

3. Legibility

Creating maintainable code is very important, and it’s one of the main drawbacks to using third party code. Most authors of third party code are not attempting to make it maintainable for the end user, and in fact it’s most often delivered minified, which makes customizing or re-engineering the code very difficult.

Good code should be written neatly so that it is easy to understand. It should follow coding conventions. It should also have comments to identify the purpose of each section of code.

When you don’t follow these simple practices, it becomes far more difficult to revisit the code later and make necessary changes to it. The need to make changes can happen more often than you may expect.

illustration by 

4. Re-usability

This is probably the most over-hyped quality of good code, but it is true that good code can sometimes be used in future programs that have similar needs. If you do a good job of developing your programs in a modular way, it is easy to re-use code multiple times.

Developing code with re-use firmly in mind from the start is not the right way to do it. Your focus should be on solving the problem that needs to be solved. However it never hurts to recognize when portions of code could be used again in other projects. The right way to do this is to write good functions that are properly designed for modularity

The ultimate goal is to avoid code duplication. You want to achieve the programming objective as simply as possible. When you use modular design techniques, you can quite often avoid duplicating code in your work.

5. Future-proofing

It’s best not to assume the problem you need to solve today is the only problem you’ll need to solve. When code can be expanded easily, without the existing code needing modification, it can be considered to be future-proof.

The basics of good code writing

There are certain code writing techniques that are considered best practice and which will save you many headaches if you follow them. The principle guidelines are:

  • Use descriptive variable names. If you’re worried about the length of variable names having an impact on loading times, then you can always use the find and replace feature in your code editor to replace long variable names in a minified distribution version. In your development version, variable names should always be as self-describing as possible.
  • Use descriptive function names. This is also important, because if the names of your functions clearly describe their purpose, it cuts down on the amount of commenting you’ll need to do. Comments are good, but you should only use them where they’re necessary. The idea of using good names for variables and functions is that comments then become necessary less often.
  • Stick to one coding style. You should avoid inconsistency in your programming techniques. If you use different styles throughout your code, then it becomes more difficult to spot inefficiency and code duplication. This rule is not just for individuals. If you are working in a team environment, all the team members should agree upon matters of style before commencing. It will avoid confusion later.
  • Test everything. Each time you add something new to the code, you should test it. If you add a lot of things before testing, it can make detecting the source of the problem much more difficult.
  • Make use of error handlers. Not using error handling is efficient but also increases the risk of code malfunctioning. If you’re writing a “Hello World” routine, it probably doesn’t matter so much, but if you’re creating some kind of routine that is used for processing a financial transaction or protecting somebody’s data, then you have a much greater burden of responsibility. Malfunctions can be costly.
  • Try to make each function perform only one task. The surest sign of amateur coding is when a function performs multiple tasks that would more properly be separated into individual functions. There are exceptions to the rule, but try to find the most efficient way.

These are not hard rules. They are more like guidelines. If you follow them, you’ll find it easy to write and maintain good code that will help you avoid the burdensome task of completely redeveloping a project. If you find that you do have to redevelop a project, it will be much easier if the code is well developed, as many former COBOL programmers who lived the Y2K era can attest.

An example of good coding style

Consider the following block of code:

 

This example exhibits the following attributes:

  • It is neatly set out and isolated from other code blocks by sectioning.
  • It is commented where appropriate, with no unnecessary comments.
  • The function name is self-explanatory.
  • The variable names are self-explanatory to anyone familiar with the jargon used in the industry the code was developed for.
  • The function performs only one primary task, which is to compute fuel burn.
  • The function is future-proof.

By using a switch operation, so that more scenarios can be added at a later time without the need to modify any of the existing code.

header image courtesy of