Fresh

Because we have a team of developers here at eROI and a plethora of projects to build and maintain, it is more than likely that the code written by one individual will need to be edited by another developer at some point in time.  When an edit to a site comes in, the original author of the code will inevitably, at one point or another, be on vacation, be sick, or no longer work here (yes, it happens, sadly).  This is why it is so imperative for our team (and any development team) to follow certain guidelines to keep our code clean and legible, so that anyone can jump onto a project, easily see what the code is doing, and start making edits quickly.  Here are five ways to keep your code readable and maintainable:

1. Indent Your Code
   This is number one on the list for a reason.  No other thing you can do can help or hinder the readability of your code than the indentation style (or lack thereof).  Nested child elements should be indented one level more than parent elements in order to show a visual hierarchy.  Opening and closing tags in HTML should be on the same indentation level in most cases; items inside the opening/closing tags need to be indented one additional level.

   <div>
       <ul id="list">
           <li>The first one</li>
           <li>The second one has a sub-list</li>
               <ul>
                   <li>One</li>
                   <li>Two</li>
               </ul>
           </li>
       </ul>
   </div>

   I will commonly place opening and closing tags for simple list items on one line; however once markup gets to be more complicated and bordering on unreadable, I will begin to break things out into an indented structure so it’s easier to see what’s going on at a glance.

2. Use Tabs to Indent, Not Spaces
   For standard indentation, use tabs and not spaces. The length of the tab can usually be configured by each individual developer within their code editing environment (one tab can equal 2 spaces, or 4 spaces, etc.) . Indenting with tabs allows for proper formatting and indentation across code editors and platforms. So, when you use tabs the indentation width can be tailored to a developer’s preference in their editor of choice.

   There are exceptions, however. Taking a page from the book of Wordpress and their coding standards: “if you have a block of code that would be more readable if things aligned, use spaces.” For example, here is a list of variable definitions, with the equals sign and values aligned using spaces to create a table-like appearance with columns:

   [tab]$foo   = 'somevalue';
   [tab]$foo2  = 'somevalue2';
   [tab]$foo34 = 'somevalue3';
   [tab]$foo5  = 'somevalue4';

3. Group code into “paragraphs”
   Give your code some breathing room!  If you’ve ever tried to read a long block of text with little punctuation and no paragraph breaks, you know how difficult it can be to read and understand.  There may be an argument that having more line breaks in a file adds to its size, adding bulk to the overall size of your webpage and increasing download time. But extra line breaks and space can be removed with minification between the time you write the code and the time it is served to the user, so there really is no excuse for not making your code readable with some well-placed line breaks.

   <ul>
       <li><a href="link.html">one</a></li>
       <li><a href="link2.html">two</a></li>
   </ul>
   
   [add some space here]
   
   <div id="content">
       <h1>Title</h1>
       <p>
           Lorem ipsum dolor sit amet
           ....
       </p>
   </div>
   
   [and here too!]
   
   <div id="footer">
       ...
   </div>

4. Use Consistent Naming Conventions
   Whether you are naming classes and IDs for CSS, or variables and functions, or directories and files, it is important to be consistent with how you name things. Here are three common naming conventions:
   • All lowercase with hyphens, e.g. class-name
   • All lowercase with underscores, e.g. class_name
   • Camel case, e.g. className

   The naming convention you use is up to you, the important part is be consistent! Personally, I avoid camel case due to case sensitivity issues – If I mistyped “className” as “classname” in my stylesheet, I could be banging my head on my desk trying to figure out why my styles aren’t taking effect before I realized I forgot to capitalize the “N”.  I much prefer dashes or underscores to separate words in variables and class names.

5. Avoid Inline Javascript or CSS
   Keep your content and HTML markup separate from style and functionality.  Being able to edit CSS and javascript from one location, instead of from somewhere scattered in your HTML, is faster and easier. Use classes and IDs properly to identify your markup elements, then refer to them from within the CSS or javascript file. Instead of this:

   <a onclick="alert('do something');" href="#">Click!</a>

   …clean up your HTML:

   <a href="link.html" class="do_something">Click!</a> 

   (Note I’ve also added a URL to the href attribute. This is for users who have javascript turned off. Those users will be taken to a new page that perhaps will show the same message as the one the javascript-enabled users will see. This is an example of graceful degradation.)

   …then, add this to a javascript file (I’m using jQuery for this example):

   $('.do_something').click(function () {
       alert('do something');
       return false;
   }

   Aside from keeping your markup easy to read and maintain, keeping your CSS and javascript in separate files will make your site load faster, because JS and CSS files can be cached by the browser while HTML files are not.

Keeping your code clean and easy to maintain is not only helpful for others who must edit the code after you; it’s also helpful for you as well! Chances are you won’t always be immersed in the code for a single project. You might be jumping around managing multiple projects, or the site may launch and you won’t even look at the code for months or even years. Sometimes the unlucky programmer who will have to deal with your messy code will be you. So make life easier for yourself, and for your fellow developer — practice good housekeeping with your code, and keep it clean!