Shadow Element

Code Philosophy

The Art of Simple, Clear, and Elegant Code

Web Code is Software

A magazine is text and graphics. All the complexity that went into creating its layout is frozen when ink hits paper. Users look at webpages the same way—text and graphics with maybe some interactivity thrown into the mix. But underlying a webpage is code. Unlike a magazine, a webpage needs to display on a variety of different devices—desktops, laptops, tablets, phones—each with different screen sizes, browsers, and operating systems. The details of how the visible elements are displayed is a collaboration between the page’s code and the user’s device.

Visible failures garner attention, but code can function properly and still be bad. Code is like the foundation of a house—important but ignored until something goes wrong.

Illustration - code underlies webpages.

Code Aesthetics for Non-Coders

To appreciate the aesthetics of code you have to “sense it,” not merely see it function—and non-coders recoil when asked to look at code. But every coder senses these aesthetics and good ones try to make their code aesthetically pleasing. Even disregarding function, the difference between “good code” and “bad code” is large. Good code is easier to read, easier to update, easier to maintain, and easier to reuse.

So what makes code “good”? For HTML/CSS, a big part is standards-based design—a coding model which separates the semantic structure of content from the way it looks. HTML is used to mark up text with tags that describe the structure of the document, but not how it should be presented. For that, CSS is used to design the look of those tags in the browser.

The separation of presentation and structure is critical to well-formed webpages. One benefit is accessibility. Blind users, for example, may experience a webpage through screen readers that are programmed to benefit from modern web standards. Page styling and untagged graphics get in the way of these users, but text whose structure has been properly coded is much easier to navigate. For example, a screen reader might be directed to read the subheads aloud until the user finds the section of interest. The screen reader knows which tags mark subheads, so long as the author has properly used them.

Google can be considered the web’s most voracious blind reader.

Those unmoved by social equity arguments for making sites accessible to the disabled might reason that blind users make up only a tiny fraction of their audience and can be safely ignored. But consider: when Google’s automated spider visits a page, it experiences it with many of the same constraints as a blind reader. In a way, Google can be considered the web’s most voracious blind reader. If the code has been written for accessibility, Google can understand the relative importance of various pieces of content and index the page accordingly. For those who care about their placement in search results, designing for accessibility is decidedly in their self-interest.

In addition to accessibility and ease of maintenance, good code allows the same content to be displayed in radically different ways by changing the way the markup is styled. The best example on the web is the CSS Zen Garden. On this demonstration page, identical HTML markup is styled with a large number of different CSS choices (choose which to apply from the links under the “Select a Design” header). The content doesn’t change, just its presentation.

Content can be adjusted so that it is well-adapted to the display. Desktop computers aren't the only game in town. Modern websites need to support devices with a variety of different widths. Phones, tablets, and laptops are all part of the mix. Some computers with high resolution “retina” screens need higher resolution images that would be inappropriate for mobile devices. And webpages aren’t always displayed on screens; sometimes they need to be printed on paper. CSS makes it possible to provide a very different experience of the same page to each of these different devices and media. It's called “responsive design,” and it’s a game changer.

The web is full of mash-ups, content aggregators, PDAs, interactive television systems, voice response systems, and even some domestic appliances, all of which may need to access content.

Finally, designing for accessibility allows for device independence. Web content is not just displayed by browsers anymore. The web is full of mash-ups, content aggregators, PDAs, interactive television systems, voice response systems, and even domestic appliances, all of which may need to access content. Someday, Siri and Alexa are going to gain the capability to read web pages aloud. Accessibility of content through proper design is the key to being able to participate in much of this activity and satisfy these different uses. “Web on Everything” is the environment in which we build websites.

Software Quality is Both External and Internal

The quality of any program can be assessed both by external and internal features.

External quality features are those that are visible to the client. They include: functionality, usability, reactivity, secur­ity, availability, and reliability. If a program satisfies those features, most clients are satisfied and accept the program.

But internal quality is also important even if it is invisible to clients and users. What is it? It sounds arcane, but internal quality is the key difference between a good program and a bad one. Internal quality is about “good code.” It means that the code is readable by other skilled developers, provides good internal docu­men­tation, has filenames and vari­ables that can be understood, is internally consistent, utilizes best practices in architecture and organ­ization, has been optimized for the task, has a clean separation between the different func­tions of the program, and is testable at least in substantial part. Ideally, each piece of code should have a clear res­ponsibility. It should have no significant duplication. If it has depen­dencies, they should be explicit. It should be well encapsulated so that one object performs its methods internally and allows other objects to interact with it through clearly defined external interfaces.

Paying attention to internal quality is an investment in the future of a piece of software. Skimping on internal quality might save time and money in the short run, but causes the program to suffer from what has been aptly called a “technical debt.” It takes longer to fix even trivial bugs. Any changes or extensions to the software require a larger effort. Maintaining the software becomes more expensive. The software is not flexible and can’t grow with the needs of the client. If the original developer becomes unavailable, it can take a larger effort for another developer to understand how the program works. Sometimes, if changes are needed in a program which suffers from particularly poor internal quality issues, the economically sound decision can be to start over again from scratch.

Good code has already identified those areas likely to change and made it easy to implement changes in those areas. Good code is flexible and maintainable. Good code doesn’t intermingle logic and presentation. If a bug is identified, good code makes it easier to fix that bug without having an impact on the rest of the program. In a project built upon open source foundations, good code is decoupled, allowing for the upgrading of key underlying tech­nologies without requiring a massive effort.

It always takes more time up front to polish code for internal quality. After one has written a piece of code that meets the external feature specifications, one must go back and refactor that code to clean it up. The extra effort to refactor code is well worth it in a reduction of errors, flexibility, upgradability, main­tain­ability, and future compatibility.

Code aesthetics can even have a marketing purpose. Analogous to typos and spelling errors, if users have a poor impression of the technical aspects of a company’s website, they’re liable to form a judgment of the competence of the company as a whole. It may be unfair, but users often judge a company’s lack of attention to such details as a general lack of capability.

Our clients usually don’t want to know what we’ve done in the underlying code. The coding should remain invisible and the site should just work.

Pipsqueak has created a system—an include-based web architecture for static webpages—to help create clean code and make our sites less prone to errors. We call it Code Modules. We’ve released it as open source software—free for other developers. If inclined, check out the repo on GitHub. Flexible enough to be used with many different web techno­logies and frameworks, we’ve been developing Code Modules over the years that we’ve building websites for our clients. Although it’s not the answer for every website, many of their websites—together with this one—are built using it.