By no means should this article serve as the bible of CSS & JS coding standards, though it should get the ball rolling for those who are unsure where to start. Over the years, I’ve had the privilege of working with many talented developers, each of whom have left little bits and pieces of their coding style behind. From those pieces I’ve assembled this article.

Let’s begin…

Alphabetize Your Code

Alphabetizing your code is an extra organizational step often overlooked. It’s especially helpful in PHP classes containing getter and setter functions, but it also comes in handy for CSS and JS. Often times similarly named elements will be somewhat related in function, so clustering them together makes them easier to find.

I’d recommend alphabetizing everything from JS class and function names, to CSS classes and ID’s. You’ll notice that every code example in this article is alphabetized to further exemplify the point.

---

Comment Everything

Comments are essential, especially among devs working in groups. The styles seem to vary slightly from person to person, but the theme is the same – you can never comment too much.

Here is my commenting style for JS / PHP:

/******************************************************
 * Cart.class.js
 *
 * A class of JS functions associated with the
 * tasks performed by the shopping cart.
 * @author Koa Metter em@mail.com
 * @copyright Copyright (c) 2010, Company
 ******************************************************/
var Cart = {

    // ...

    /**
     * Add item to cart
     * @param string item_id
     * @param string item_quantity
     * @todo Check for string validity
     */
    addCartItem: function (item_id, item_quantity)
    {
        if (!Utilities.isEmpty($('#cart-items')))
		{
			Cart.AJAX({
				data: 'call=addOfferingToCart&args[0]='+item_id+'&args[1]='+item_quantity,

				// Things we'd like to do upon 'status => success' ajax response
				success: function (msg)
				{
					Cart.displayNewCartItem(msg);

					// Update cart total price
					Cart.displayCartTotal();

					// Also update checkout rebilling terms!
					if (msg.response.rebilling_terms_agreement){
						$('#billing-terms-agreement-label').html(msg.response.rebilling_terms_agreement);
					}

					Cart.proceedBtnCheck();
				}
			});
		}
    }

}

When commenting in PHP, phpDocumentor can be used to build a comprehensive dev manual for your source code. I use the same documentation style for JS simply because I come from a PHP background.

Though CSS doesn’t need the phpDocumentor-type of commenting, it should nevertheless remain detailed to explain the elements and their purpose. Clustering elements that are related to the same stylistic area or function of the website helps in organizing without the need of many comment blocks.

---

Indent CSS

Indenting your code is an obvious standard with most programing languages, but often times CSS is left out of the loop. Indent a CSS element if it’s a child of a parent element, like so:

#container {
    color:#222;
    width:100%;
    z-index:1;
}

    #container .lg-block {
        height:300px;
    }

    #container .sm-block {
        height:100px;
    }

.etc {
    /* ... */
}

The above CSS example shows that the class .lg-block is specifically contained within the ID #container, thus we are indenting it to visually represent the same thing.

---

OOP-ish Javascript

This topic deviates slightly from actual “coding standards”, but I think it’s equally important – how to format your JS into usable, organized classes. This rule takes into account all other coding standards (alphabetization, indentation, commenting, etc) and applies them to JS, adding in OOP-like objects.

Here’s an example:

var Vehicles = {
    /*
     * Give us the word "Bus"
     * @return string
     */
    bus: function ()
    {
        return 'Bus';
    },

    /*
     * Give us the word "Car"
     * @return string
     */
    car: function ()
    {
        return 'Car.';
    },

    /*
     * Give both car() and truck()
     * @return string
     */
    getCarAndTruck: function ()
    {
        return this.car + ' and ' + this.truck;
    },

    /*
     * Give us the word "Truck"
     * @return string
     */
    truck: function()
    {
        return 'Truck.';
    }
}

// Let's call the function getCarAndTruck like so:
Vehicles.getCarAndTruck();

Shuffling your JS into objects helps associate functions with tasks / groups and thus creates a more organized codebase.

---

Hopefully this helps. If you have a different method of commenting and/or organizing your CSS or JS code, let me know!