Good code, Bad Code – It’s all about good habits. – deathshadow – Apr-22-2009 07:36 PM About six months ago I posted this on various forums, I figured I’d share it again here for those who aren’t afraid of reading or reason. I’ve also gone through and ‘punched up’ the text a bit. In a number of threads on various forums I have talked about coding habits and Minimalist Semantic Markup. The driving force behind MSM seems to be three rules I learned ages ago when home computing was more myth than fact. It is more than just the ‘semantic markup’ you hear mentioned, as being semantic is not enough. I coined the term ‘minimalist semantic markup’ combining my own minimalism with semantic markup for a reason, and am quite proud of the fact a few others have picked up on it. To review, those rules I learned three decades ago were: 1) Program interfaces should concentrate on the user FIRST. As a programmer put your ego aside and concentrate instead of what the user wants. 2) Proper formatting, indentation and good commenting can prevent more errors than an entire boatload of debugging tools. 3) The less code you use, the less there is to break. ———————————————- The first of these can be seen by the movement of separating content from presentation, and ‘flipping’ the design process around backwards to work with CONTENT FIRST. The content is what the visitor is coming to your website to see – EVERYTHING else is secondary, should not get in the way, and in general is not as important. If content is indeed the most important thing on a page, WHY THE DEVIL do ‘designers’ start out in a paint program drawing pretty pictures, then shoe-horning their content into it? Doesn’t sound right to me. Even if you have the pretty picture already done, the first step for turning it into a page should not be image slicing, but starting out with markup up the content semantically.

My design process, and the one the handful of us advocating the concept of ‘MSM’ are advocating, is that you markup your content first using semantic markup with NO CONCERN for what the final page is going to look like. Certainly you might include some DIV containers to group various ‘sections’ like content and sidebar together, and a master #container div is always a good idea, but apart from that when making your HTML the last thing you should be thinking is ‘appearance’. What you should be thinking about is WHAT IS IT I am marking up. Is this a heading, is this heading a subsection of the previous heading or kin to it? If it’s kin, is the previous heading a h1? If so then it shouldn’t be. Is this a content paragraph? These italics I’m seeing in my copy, is it because of a book title like Moby Dick or text that is getting special emphasis – if you know what I mean. These images I’m adding, are they actually part of the page content warranting an image tag, or are they strictly presentational belonging in the CSS?

Once you have ALL of the content that is going on the page marked up, you start making your layout in CSS, bending that HTML to your will. Wherever possible adding to the html any sort of presentation or extra hangers should be avoided – though inevitably things like image sandbags may be required for things like glider-levin image replaceemnts or sliding doors. Most importantly TEST every major ‘section’ change in EVERY browser you can lay your hands on AS YOU GO. Time and time again you see on forums people asking “I have this layout completed in FF, and it’s broken in IE” – Their biggest mistake was completing the layout before even THINKING about testing it!

Then and ONLY then should you start up the goof assed paint program to hang graphics on your layout, or try to slice up that PSD made by the ‘designer’ who wouldn’t know accessability from the hole in their tuchas. ———————————————-

The second rule is one people have gotten incredibly LAZY about. Over-reliance on tools like htmlTidy, and rubbish like code completion and the ‘acid trip’ colour syntax highlighting have gotten programmers out of the habit of bothering to JUST WRITE CODE CORRECTLY IN THE FIRST DAMNED PLACE! If you master the tab key, don’t go nuts trying to compress everything to a single wrapping line (that **** really torques my nuts) and learn what tags are deprecated in your doctype – guess what? The only thing validation is likely to be needed for is checking to typo’s.

Another part of rule 2 is commenting – These days bad commenting is WAY more prevalant than a lack of commenting, and in a lot of cases the comments people use are pointless, silly and in the case of some of them, likely to trip rendering bugs in IE. (the much feared “Double Render” and “Dissapearing Content” quirks) Take this example: (apologies to the forum who’s deployed code I took this from!)

Code:

No, really? It’s the start of the navigation? I never would have guessed that a DIV would be the start of a block, or that the block would be a ‘nav’ given that it’s it’s class name is Navigation. This is the PINNACLE of piss poor commenting. On the flip side we have:

Code:




You don’t need to say ‘end’, we know what means. Likewise wouldn’t it be more meaningful to list the classname and not some vague abbreviation? This also puts the comment after the DIV. If in some skin we decide to float that div, the placement of the comment could trip those two pesky IE rendering bugs I mentioned because it would end up between .navigation and the table after. (and tables are well known to do the double render next to floats). Now, saying the name of the close is a good idea if the two end up more than 8-10 lines apart, or for ‘major’ section blocks so we do want something there – solution? Move the comment BEFORE the – which is why my own style guide says to do it thus:

Code:

Proper meaningful helpful comments are important – commenting for commentings sake is not. A good writeup on the topic of clear comprehensable code is available on IBM’s linux website. It is extremely insightful and I believe should be read by anyone serious about writing code:

http://www.ibm.com/developerworks/linux/library/l-clear-code/

You’ll notice I said ‘style guide’ – I’m a firm believer in consistancy of code formatting. Every programmer should be able to work within a style guide, and for their own use either adopt an existing style guide, or develop their own distributing it with all of your works. It gives other programmers a clue what you are doing – though if you use verbose meaningful classnames with a consistant indentation format, with consistant use of carriage returns to make blocks clear, it is doubtful few will ever have problems with whatever else you do in your ‘style’ For reference, the most recent revision of my style guide for HTML/CSS/JS is here:

http://battletech.hopto.org/html_tutorials/styleGuide.txt

(ok, that’s actually out of date and missing a paragraph, but you get the idea)

I tend to also use the above for my own PHP code for consistancy instead of the ‘recommended’ which to me is a confusing jumble. God forbid you use the same indenting and formatting styles for HTML, CSS, JS and PHP. ———————————————- These first two rules combine well with the third rule, which EVERYBODY knows as the KISS theory. An excellent example of this would be a contact form I was rewriting for a client last month. It was built off a framework example from their goldmine application – and was one of the WORST train-wrecks of code I’ve seen since the last time I poked my head into a turdpress installation. First off before we even TALK overcomplicated code, it had major ‘logic flow’ and security issues. The goldmine template for a contact form passes the username, password and URL to the e-mail server in a simple subtractive hex hash in hidden inputs IN THE FORM SENT TO THE USERS BROWSER!!! Anyone who knows what algorythm is used to encode this data could simply view source on the contact form, then hijack the e-mail server for their own purposes. WHAT NIMROD THOUGHT THIS WAS A GOOD IDEA?!? Worse, the code they used to decode the hash was unbelievably overthought. Get a load of this PHP:

Code:

function Decode($strValueIn) { //Do not modify this function! $intX = 0; $intY = 0; $Temp = ""; $Mod = ""; $intMod =0; $intTemp = 0; $ValueOut = ""; $intY = 1; $strValueOut=""; for ($intX=1; $intX