The Challenge

Everyone who codes has their specific way of doing things. It's impossible to avoid. This presents a challenge in a company where every developer and engineer may need to work on projects that he or she did not originally complete. How do we make sure that we are as efficient as possible? Standardization.

Advantages and Disadvantages

If you have ever worked on code that someone else has written I am sure you have at some point gotten confused, frustrated and had this dreaded thought, "I could write this again from scratch quicker than I could fix this code". This is such a common feeling. Understanding the logical thought process of another person can be difficult and time consuming. It seems like standardization would be a no brainer. It seems...

I am also sure that at some point while working through another person's code you have had an "A-HA!" moment as well. The moment when you realize what elegant algorithm was used or how a problem is solved in a way that just would not have occurred to you.  As frustrating as it can be to work with other people's code, it can be a fantastic learning device.

So how do you balance the need for familiarity and efficiency with the need for learning and idea exposure?

Our Journey

During my tenure at VisionPoint Marketing, we have worked to standardize our coding practices three times. Each time yielded some different results for different reasons.

As any coder knows, no one likes to be told how to code. Writing code is problem solving and every programmer has his own style. Handing down a pre-ordained dictum of coding style in a company this size just makes programmers feel boxed in. The key of these meetings is input and buy-in. We want every developer and engineer at VisionPoint to have input in our style and bring their own ideas to the table. 

When I started working at VisionPoint, I was the second developer and as a result I pretty much standardized to the style of my mentor, David Millsaps. He taught me everything I needed to know to write bulletproof HTML and CSS and I followed his lead to keep our code in similar style. I mainly adapted to his file and directory naming schemes as well as CSS structure. At that time we were still making non-CMS driven websites and these were the most important things to standardize on at the time.

Upon the hiring of our third engineer, Ulisses Gurgel, David, Ulisses and I decided to sit down and have a meeting and hash out exactly how we want to code so that we will all recognize each other's work regardless of whether or not we actually worked on the project. We mainly focused on HTML div naming as that is where we had the most competing ideas. The biggest revelation that came out of that meeting was to make sure we are naming divs based off of their type of content and leaving out naming that may have to do with on page location. Gone were the days of id="right-column" and id="center-bottom". In were the days of id="secondary" and id="promo".  As much as it may make sense to name things based off of page location, we decided that it violates the tenant of keeping design separate from HTML. As web developers we always love the (slightly unrealistic) idea that a website can be re-skinned completely without touching the HTML. This seemed like a step in that direction.

After the departure of David Millsaps and the hiring of our newest developer, Erik Olson, and newest engineer, Chris Francart, we had another one of these meetings and we worked to make sure our code was in a similar style which I will outline below.

Our Solution (still in progress)

Here is the standardization we are now testing in our website development.

File and Directory Naming

This was pretty easy as we were mostly on the same page already.

  • Images - This folder contains images that are used as content rather than images used for design purposes.
    • We have sub-folders named for each section of the website so that they remain organized.
  • Dress - Similar to the idea of clothes, our dress folder holds all the design related files including CSS and design images.
    • Global - In order to be in the global folder, you must be loaded on every page of the website.
      • Blueprint - This is a CSS library we use. We keep it in its own folder for easy updating should a new version come out.
      • Folders for each template type or section to keep everything organized. These folders contain the CSS and design images that are unique to that section or template.
  • JS - This holds all out JS used on the site. We try to limit on page JS as much as possible and keep everything we can in files.
    • Lib - This sub-folder holds 3rd party scripts like JQuery.
    • Sections_of_the_website.js - We then have files named similarly to the folders in the dress folder. These hold the JS needed for the specific sections or templates used on the website.

HTML

This was a harder thing to stardardize as every website is a little different and as much as no one wants it to... sometimes design dictates HTML. We use the CSS library and grid system, BlueprintCSS, so some of our naming is based off of that. We decided to adopt a few naming conventions for the more important and common divs while allowing developer freedom within those divs.

#container - This is the outer most div and contains (hopefully) everything on the page.
#column - Lives right inside #container and contains (hopefully) everything on the page.
#header - This is the top of the page including the logo, some navigation elements and anything else.
#utility - This is for non main navigation elements found in the header.
#navigation - This contains the main navigation in nested UL's.
#content - This is the div inbetween the header and footer and contains all of the content of the page.
#secnav - This lives inside of #content and contains the section navigation.
#billboard - This lives inside of #content and is found on some pages and contains large graphical features.
#primary - This lives inside of #content and contains the main text content of the page.
#secondary - This lives inside of #content and contains secondary content such as related articles, tags, promos and other secondary content.
#promos - This lives inside of #secondary and holds all the promos on the page.
#footer - This is the footer of the website.

CSS

How in the world do you organize CSS in a way that makes sense? We have tried to answer that question plenty of times. Previously we had a loose order to keep commands in that came from my mentor's method of thinking through styling. This worked well for us but as we added on more developers and engineers with their own experiences, it became harder to really justify that order as other's think through things differently. We finally decided on something that made us all a little uncomfortable at first but will at least be reliable. 

  • The CSS selectors should be in the same order that they are found in the HTML. 
  • The CSS commands will be kept in alphabetical order. 
  • Divs will have comments around them dictating the beginning and end. 
  • Each command's value will be tabbed over 4 or so times so that they line up creating a visually pleasing and less cluttered look.    

ExpressionEngine Template Naming

We have not taken out standardization beyond ExpressionEngine (EE) yet as it is the most flexible when it comes to template naming. Here is what we are applying in EE.

  • Includes
    • .foot - This contains all the end tags for anything that was started in .head.
    • .footer - This contains the html footer.
    • .head - This contains the doctype, html, and head tags.
    • .header - This contains the html header.
    • .navigation - This contains the main navigation that is used throughout the website.
    • .scripts - When passed a variable, this loads the proper scripts onto every page.
    • .styles - When passed a variable, this loads the proper CSS onto every page.
    • .utility - This contains useful nvaigation that commonly appears in the html header.
    • .secnav - When passed a variable, this loads the proper section navigation onto a page.
  • Promos
    • .director - When passed a variable, this builds the proper promo to display.
    • .news - This is a recent news promo, pretty common on our websites.
    • .events - This is an upcoming events promo, pretty common on our websites
    • .default - This loads promos that users can create in the default style.
  • Pages - This holds various page tempaltes for the site.
  • News - This holds all the templates needed for the common news section.
  • Calendar - This holds all the templates needed for the common calendar section.
  • Landing-pages - This holds any landing-pages for PPC clients.

Future Challenges

After testing out these decisions, we met again to see if anyone was hitting any issues. We decided to continue with these and to add to our standardizations as projects come up that require them. The only issue we are still working to solve is that with how quickly the web is changing and new technologies are becoming available, how will our standardizations have to change? If our standardizations are always changing, are they really standardizations anymore? We will have to see where we are in a year or so and evaluate from there. Oh the life of a web developer.