How to Keep Your Code Clean, Readable & Accessible

By Neill Harmer, Lead Designer at LightCMS

If there is one piece of advice all HTML and CSS coders should follow, it would be: Whenever you write code, spare a thought for whoever has to read and modify your work in the future.

When developers and designers write code with the reader firmly in mind, they can focus on the importance of creating clean, readable and accessible code, which not only makes sense in the moment it is being written, but is also fully comprehensible in a year or two.

Consider the different potential audiences for code including the original coder, other members of a development team or those of a third-party partner and even clients. Code should be thought of as a way to communicate with those different readers. Clean code is like a well laid out and error-free business letter where time has been taken to write clearly and without ambiguity. Contrast that with less thoughtfully written code, which often resembles a hastily scrawled note full of spelling and grammatical mistakes - leaving it open to misinterpretation.

Writing for Readability

Writing cluttered and poorly organized code might seem like a quick fix at the time, but it may result in extra work. Imagine returning to fix, maintain, update or build upon code you wrote that uses bad naming conventions or lacks structure. Valuable time can be wasted trying to navigate that code and working out previous intentions - and you're the original author. Just think how much tougher it will be for others to read that same code.

When working with a team of developers, it is necessary to have a set structure and agreed-upon coding style so that it's easy to work on someone else's code. By doing so, development and design teams will avoid ending up with a jumbled mess of code that's difficult to work with and decipher. Furthermore, as new staff is added, they too must be educated on the organization's coding style and adhere to it so that the code produced looks as if it were written by one single developer and not by multiple individuals. Those writing code also need to think about the client.

Write code with the expectation that clients will eventually want or need to make their own changes to it. For instance, plan on including an index at the top of the code to let clients know where particular elements can be found. If a client has trouble reading and navigating the code, any changes they make may end up tangling the mess of original code still further, ultimately resulting in a poor-performing website.

One general rule about writing code is this: less is more. At the very least, clean code translates to a faster running website. The advice provided below should reveal how the result of writing clean code is almost always less code.

Writing Clean HTML

Let's look first at HTML and some of the basics around code structure. Focusing on the following areas will help designers and developers generate clean code every time:

+ Grouping. Consider how elements are placed together in code as a way of aiding navigation. Keep code linear with a clear flow from the header at the top to the footer at the end.

+ Naming. Use naming conventions that are not overly specific. The danger in opting for a column name, for example, that references a particular color or font style or position in relation to other code elements is that all of the above are likely to change at some point in the life of the code. Overly specific names may no longer make sense in the long term, so choose wisely. Ensure that the development team all uses the same style for class names so there's no variance, for instance, in how a name might be capitalized, hyphenated or underscored.

+ Tags or Attributes. Use the correct tag or attribute and, in particular, think about whether divs are being overused as block-level code elements, like paragraphs of text and images, are grouped.

+ Indentation. One key thing in making code more readable is to indent where necessary so it's clear when a new code element, perhaps a child element of the tag above it, is introduced. Be consistent when applying indentation within code so the hierarchy is clearly delineated and readers can use indentation as a way to navigate through the code. Overly dense code is difficult to read, so remember, white space is every coder's friend.

+ ID versus Class. When applying a particular style to one or more code elements, make sure to use IDs or classes. An ID is for a unique element so it should only occur once in the code - ideally in the sections for a website logo or header or footer. A class like "quote" however, can be used over and over again.


Who Codes in 2015?

According to a Stack Overflow study:

+ 29 years old is the average age of a developer, worldwide

+ 92 percent of coders are male

+ 25 percent of developers worldwide have more than 10 years of coding experience

+ 48 percent never received a degree in computer science

+ 42 percent are self-taught

See more at wsm.co/whocodes15


Writing Clean CSS Code

Now, let's turn to CSS and some of the basics around code structure. Again, grouping, naming and indenting code are very important factors in writing clean, so much of what was addressed previously about HTML also applies to CSS. In addition, focus attention on these three areas specifically:

Alphabetical Declarations.

Chances are high that developers will find they write the same lists of descriptions multiple times in a single piece of code; e.g., "font, width, border, margin, padding." Putting that list in alphabetical order "border, font, margin, padding, width" not only makes for better readability but will make it easier to immediately spot and correct any duplication of terms.

Vendor Prefixes.

This is an area that changes regularly so make sure to keep up to date on what browser vendors are using for prefixes so code has the best browser support (also consider hand coding or using third-party text editor services to help plug in the most current vendor prefixes or fully automate that process).

Comments.

Adding comments to code can act as a visual memory aid to clearly indicate why a developer did what they did at a particular point in time. Consider writing comments in a straightforward and conversational tone so the meaning is very clear. Many find it particularly useful to add in a comment whenever the code includes a mathematical calculation, for example, in order to flag and explain which kind of calculation is being performed and how the result of that calculation should be expressed.

Clean Code Is Usable and Reusable Code

HTML and CSS code form the building blocks of well-designed websites, so why not apply the lessons of great website design to coding? Think about clear and uncluttered layouts, easily comprehensible navigation and all the potential readers who may visit the finished work. Write clean, readable and accessible code for the benefit of your future self, your peers, partners and clients.