Clean Code is Organized Code!

A lot of people never look under the hood of their website’s code. It’s just something most people either a) never bothered to learn or b) don’t really want to fool with. However, in the world of budget woes and the proliferation of easy platforms like WordPress, more and more people are adopting a “do-it-myself” view when it comes to their web presence, both personal and business.

However, coders building website templates — even the big ones like StudioPress, WooTheme, and Thesis — code like, well, coders. I think we need to start coding a little bit differently. With more spacing, more comments, and, yes, a little more effort. Here’s what I’m talking about — and, what I’m doing with my own themes:

Tabbing and Spacing

Unlike computers who just see syntax, we actually have to look at and read the code. To do that, some basic formatting is required — not for computers, but for us poor humans. Proper tabbing and spacing is an essential element of that. Here is an example of untabbed code:

[code]#title-area #title {color: #222222; font-size: 42px; font-family: ‘Oswald’, Arial, Tahoma, Verdana; font-weight: normal; margin:0px 0px 0px 150px; padding: 0 0 0 20px; text-decoration: none; line-height: 48px;}
#title-area #title a {color: #222222; margin: 0; padding: 0; text-decoration: none;}[/code]

And here is the same code properly tabbed and spaced:

[code]#title-area #title {
color: #222222;
font-size: 42px;
font-family: ‘Oswald’, Arial, Tahoma, Verdana;
font-weight: normal;
margin: 0px 0px 0px 150px;
padding: 0 0 0 20px;
text-decoration: none;
line-height: 48px;
}

#title-area #title a {
color: #222222;
margin: 0;
padding: 0;
text-decoration: none;
}[/code]

Now, take into consideration even a small website is about a thousand lines of this. Which would you prefer to read? Which do you think is easier to find things in? Thankfully, most of the major template makers code this way — it really is easier all around. If you grab a theme that looks all un-tabbed and messy — do yourself a favor and dump it. Don’t settle for jumbled code!

Comments

Code is pretty much it’s own language, unique from any other. But, you can learn to read it and after a while it is pretty transparent. Much, I assume, like it is when a person is submerged in a foreign culture — you just start picking it up. However, I don’t think that is an excuse to not give a few plain language pointers, notes, and directions here and there. Every little bit helps, and making your code “newbie” friendly is a good idea. That means comments — both plentiful and helpful! Don’t leave people fumbling around in the dark — comment meticulously! So, instead of seeing something like this:

[code]#header ul.nav li a:hover, #header ul.nav li a:active, #header ul.nav .current_page_item a, #header ul.nav .current-cat a, #header ul.nav .current-menu-item a, #header ul.menu li a:hover, #header ul.menu li a:active, #header ul.menu .current_page_item a, #header ul.menu .current-cat a, #header ul.menu .current-menu-item a {
background: #000000;
color: #FFFFFF;
}[/code]

Try something like this:

[code]/** Rollover effect and coloration for Header Menu Navigation items **/

#header ul.nav li a:hover, #header ul.nav li a:active, #header ul.nav .current_page_item a, #header ul.nav .current-cat a, #header ul.nav .current-menu-item a, #header ul.menu li a:hover, #header ul.menu li a:active, #header ul.menu .current_page_item a, #header ul.menu .current-cat a, #header ul.menu .current-menu-item a {
background: #000000;
color: #FFFFFF;
}[/code]

Organized

By nature, many coders are organized. The problem that those using their code find are that they are organized for efficiency, not for use. When I say this, I mean that if an argument is repetitive, many coders will handle them all at once so that it saves time. That results in code looking like this:

[code]#content #featured-top h2, #content #featured-top h2 a, #content #featured-middle h2, #content #featured-middle h2 a, #content #featured-bottom h2, #content #featured-bottom h2 a {
color: #ffffff;
font-family: ‘Oswald’, Arial, Georgia, Times New Roman, Trebuchet MS;
font-size: 20px;
line-height: 26px;
font-weight: normal;
margin: 0;
padding: 0;
border: none;
}[/code]

The above code dictates the settings for three layers of widgets on a widgetized home page. Normally, these are all the same and so it is more efficient to just group them all together. However, when you start customizing and tweaking, this type of coding is enough to drive you absolutely CRAZY! You may spend hours – literally hours! – trying to find some small CSS variable amidst thousands of lines. This is just a single header code — you’ve got multiple headline options for each widget, not to mention background colors, sheet options, margins, etc, etc. And then there are the page-wide and site-wide characteristics! It gets out of control in a hurry, I assure you.

I recommend keeping all of the relevant code for a given function or section discrete and together. Yes, for those coding, this does mean a lot more work on the front end. You may have to write 15 different lines for what 3 lines would have done using the “efficient” method. But, that time investment will pay itself back in spades whenever you dive back into that code to make a tweak or correction. So, instead of searching all over the entire CSS Stylesheet to customize a particular widget, you just go there and get it done. Here’s an example from this site:

[code]/** Leftmost Widget in the Middle Row on the Home Page **/

/** General shape and colors **/
.featured-middle-left {
background: #222222;
width: 270px;
height: 270px;
float: left;
margin: 10px 10px 10px 10px;
padding: 9px 9px 0 9px;
border: 1px solid #FFFF00;
}

/** Wrap and Widget settings **/
#featured-middle-left .wrap, #featured-middle-left .widget {
margin: 0;
padding: 0;
}

/** Paragraph Settings **/
#featured-middle-left p {
margin: 0;
padding: 0 0 9px 0;
}

/** Image Settings **/
#content #featured-middle-left img, #content #featured-middle-left p img {
max-width: none;
}

/** Headline H2 fonts and colors, both standard and active **/
#content #featured-middle-left h2, #content #featured-middle-left h2 a {
color: #ffffff;
font-family: ‘Oswald’, Arial, Georgia, Times New Roman, Trebuchet MS;
font-size: 14px;
line-height: 16px;
font-weight: normal;
margin: 0;
padding: 0;
border: none;
}

/** Headline H4 fonts and colors **/
#content #featured-middle-left h4 {
color: #ffff00;
font-size: 20px;
font-family: ‘Oswald’, Arial, Georgia, Times New Roman, Trebuchet MS;
font-weight: normal;
text-align: left;
margin: 0 0 5px 0;
padding: 0;
}[/code]

Now, this is far from efficient as much of the above code could be standardized and compressed, certainly at the widget-row level at the very least. But, that wouldn’t give clear, concise, language to each level and item of the site. Is it more work to write a template this way? Definitely! By an order of magnitude. BUT, once you dive back into that code to tweak it, you’ll be glad you made the investment. In addition, I would posit that writing themes this way makes it much more marketable, as it enables easier customization by inexperienced coders.

Happy coding!

About Rob McClellan

Rob is the founder of ThirdScribe, a unique author services platform and social network. As a naval officer and diver, he spent a majority of his career doing a lot more than you would think with a lot less than you can imagine -- a skill that has proven extremely valuable in the start-up world. You can follow him on Facebook, Twitter or Google+.

4 Responses to Clean Code is Organized Code!

  1. Here Here!

    My first time debugging code was a real challenge. The first and usually only comment of the various .c files was exactly the same in each one. After parsing through triple plus embedded statements on one line, I was thrilled to find a Unix utility called cb (c beautifier). Saved me endless hours I’m sure.

    It’s nice to see posts like yours.

    :-{>

    • Profile Cover Art

      Thanks, Kurt!

      I wrote this post after spending hours trying to find a single identifier for a widget title — that was WAAYYY down the sheet in a totally unrelated section. So frustrating! I’ll look into code beautifier, sounds useful indeed.

Leave a reply

Your email address will not be published. Required fields are marked *