10 Rules to Code By

Over the last few years the We-Create development team has built up quite a few unwritten rules that have helped us create some excellent code. You will probably recognize a few, but I doubt anyone knows them all. Therefore it’s time to write them down, understand their reasoning and live by all of them all of the time.

1. All users are evil.
2. Design for users, not programmers.
3. JavaScript must only be used for interface enhancements.
4. Clean separation of logic, presentation and interface every time.
5. Semantics matter.
6. Standards matter.
7. Document or die.
8. Security through obscurity is no security at all.
9. KISS: Start simple. Enhance later.
10. Use the team. We’re on your side.

1. Assume all users are evil.

This isn’t literally true since the vast majority of our users are not, in fact, evil. However, for security’s sake we must assume that they all are. Even computer savvy people with privileged access to a system can be corrupted or have their computers hijacked by evil people. Therefore, all of our software must defend itself from compromise in every possible way.

Moreover, some users are evil without even knowing it. They will make mistakes and do things that we are not expecting. They might stumble upon a case we haven’t tested for, or do things in a different sequence than our design assumes. Therefore, every piece of data that can be modified by the user should be checked and rechecked before trusting it in any way. This includes not only escaping SQL special characters, but ensuring that the type of data is correct and comparing it with the data we have already accepted to ensure that the information makes sense in context.

Remember that POST values can be manipulated just as easily as GET values, so treat them both as equally unsafe data. Also, don’t trust the cookie data without checking first, even if you think it is encrypted or otherwise protected from manipulation (see rule #8).

Lastly, there is no such thing as a system that is 100% secure, but we can strive for 99.9% if we try hard enough. Place security as the first and primary design objective and consider it from the start in everything you do. Going back and securing code after it’s “done” doesn’t work, and it’s not done until it’s secure.

2. Design for users, not programmers.

One of the best ways to prevent users from making mistakes that cause security problems is to properly design the user interface so that it is intuitive and guides the user down the right path. This is much easier said than done. However, consider the case of GET versus POST values mentioned above. Making a conscious decision to place any parameter that would allow a user to bookmark a page’s state in the GET values helps them to use their browser as they expect. Additionally, using POST values for anything that needs URL encoding can help demystify the address that they can see and sometimes dissuade them from manipulating it directly.

The most important thing to remember is that there are many ways to implement a feature, and some are more correct than others. Therefore when a decision is being made we must remember that non-programmers will use the end result and they tend like things sites and tools that are clean, easy and intuitive. If a feature can be implemented in two or more ways, select the one that is most intuitive for the user. It’s likely also the most intuitive to implement and maintain as well. The user will thank you and the extra effort always pays off in the long run.

3. JavaScript must only be used for interface enhancements.

Our rule is that if it doesn’t work with JavaScript disabled, then it doesn’t work at all. This applies to all forms of JavaScript, including AJAX. Even a so-called “Web 2.0″ site should at least be usable on non-javascript browsers, even if it doesn’t look pretty or behave the same way. All content should be accessible via the traditional request-response web model from the early 1990′s.

Some of the biggest offenders are menu systems (like BostonPizza.com) that are built to be flashy by novice JavaScript programmers. A better approach is to make a system work entirely without JavaScript, then check to see if JavaScript is available. If it is, then, after the document is loaded (onload), use the DOM to manipulate the document and restructure what the user sees.

We dare you to try surfing the web with JavaScript turned off for a day. You’ll be surprised how many walls you run into in the first few minutes. This is not acceptable.

4. Clean separation of logic, presentation and interface every time.

Mixing markup (XHTML), CSS and JavaScript in a single document is almost as evil as our users are. There is never a need[1] to add inline styling (such as with the style=”" attribute), that can’t be better handled with proper ID and CLASS definitions and an external CSS file. The same rule applies for JavaScript. If your code design prevents you from putting all JavaScript functions in an external file, then you need to re-consider your design.

Not only does separating the markup/structure from the logic/presentation help when debugging, but it also helps with modules when a designer has to change the layout for different sites. Being able to grab hold of a nice CSS class/id handle instead of editing the PHP directly simply makes life easier for everyone.

Lastly, properly structured code is much easier to debug, so while the setup might cost you time in the design and alpha stages, it will save you (as much or more) time when dealing with the list of bugs that inevitably comes back from the beta-testers.

[1] See the comments for a load-time argument for mixing in at least height and width tags.

5. Standards matter.

Not every browser renders a standards-compliant document correctly or completely, but some do. Develop the system entirely for one browser that IS standards compliant (say FireFox 2.x), get everything working and validating then go back and add specific hacks for poorly built browsers like Internet Explorer.

Also, don’t strive for pixel perfect matches between all of the major browsers and versions. No user other than someone on the beta-testing team is ever going to do a side-by-side comparison. Simply ensure that the system works as intended, is bug free and looks reasonably close to that of the standards-compliant browsers. In the long run as people adopt newer browsers that are more standards compliant your system will be future-proof and continue to work properly.

Lastly, remember this quote from Yahoo’s article on Graded Browser Support:

“Support[ing multiple browsers] does not mean that everybody gets the same thing. Expecting two users using different browser software to have an identical experience fails to embrace or acknowledge the heterogeneous essence of the Web. In fact, requiring the same experience for all users creates a barrier to participation. Availability and accessibility of content should be our key priority.”

Amen.

6. Semantics matter.

Semantically marking up a document allows a machine to obtain the same meaning from the document as a person would. The machines specifically we care about are screen-readers for the blind. You could argue that this represents an extremely tiny fraction of our overall visitors to any site. That is until you consider that the search engine spiders are blind too. Spiders see ONLY code and rarely download the CSS and JavaScript to do anything more than verify that you’re not trying to hide something deliberately (ie. Black-Hat SEO). So not using semantics means you’ll fewer visitors and also makes an obscene body gesture to those who are less fortunate.

That’s all well and good, but how do we produce semantic markup? Simply use tags and CSS classes that describe the meaning of the content rather than the visual appearance of the content or page. Here are a few examples:

* Don’t use <div class=”bigBlackText”> when you could use <h1>
* Don’t use <h1> when you really mean <b>
* Don’t use <b> when you really mean <strong>
* Don’t use <i> for emphasis, or <em> for italics
* Don’t use tables or divs to define a menu, since it’s really a list
* Don’t create containers like <div id=”LeftColumn”> when you mean <div id=”sidebar”>

Do you know about the <dl>, <dt> and <dd> tags? What about <abbr> and <acronym>? Yes? Ok then, do you know about <ins> and <del>? Be honest.

You get the idea? There are many things in our scripts that don’t yet have semantic markup tags in XHTML. For those use div and span containers with IDs and CLASSes that mean something. At least then a machine has a chance to understand what you are saying.

More info: http://www.digital-web.com/articles/writing_semantic_markup/

7. Document or die.

UPDATE Feb 2010: I’m less of a zealot about this particular rule these days. Overall we’ve adapted this rule to become more of a “Design, plan and document or die”. In essence, if we don’t have a firm, concrete plan with requirements, specifications etc in place, then we don’t proceed. Maintaining comments is part of that but not all of it. – Cam

Good, clean, high quality inline code comments make everyone’s job a lot easier. With a team that has dozens of projects on the go at any given time, your uncommented code could become someone else’s code nightmare seemingly overnight as teams are rearranged to meet the demands of new projects.

A good habit to get into is to begin a new file and then write out your entire plan of attack using only comments before writing any code. Once the strategy is laid out using comments go back and fill in the code between them. For example, simply adding a comment block to the head of a 200-line function doesn’t always help someone who is trying to fix the function if there is ever a problem. They need to know what general methodologies you used, what your plan was and why you did something a certain way before they can begin to see if you did it correctly. Of course, you can safely assume that once another programmer knows your plan, and the reasoning for it, they can read the code itself to figure out how it was done.

The best test you can use to check if your comments are good enough is to read only the comments and see if you understand the goal and plan behind making that goal a reality. If you need to read any code to understand that much then you need more comments. For those of you who insist on numbers, the ratio of code to comments should be someplace between 1:4 and 1:8 (by lines).

Here is a simple example of what I’m talking about:

EDIT: The header for this function has chanced from the original. See Jeff’s comment below for the original version.

/**
 * Validate the authenticity of a one time ticket
 *
 * This function takes a 32 character MD5 string and determines if it is a
 * valid, unused, recently assigned nonce. Used primarily in the login
 * function before comparing hashes sent by the user.
 *
 * @param resource $conn The connection to the database
 * @param string $ott The one time ticket hash
 * @return boolean true if valid, flase otherwise
 * @author Cam Turner <***********>
 * @see http://en.wikipedia.org/wiki/Cryptographic_nonce
 */
function validate_one_time_ticket($conn,$ott) {
	global $AUTHENT_CONFIG, $conn;

	// Validate the data is as we expect
	if (!check_type($ott,"MD5")) { return false; }

	// Verify that this OTT was assigned by us previously
	$query = db_query($conn,"SELECT * FROM one_time_tickets WHERE one_time_ticket='$ott'");
	if ((!$query) || (db_numrows($query) != 1)) { return false; }
	extract(db_fetch_array($query,0));

	// Remove the OTT from the DB so that it can't be used again
	$query = db_query($conn,"DELETE FROM one_time_tickets WHERE one_time_ticket='$ott'");
	if (!$query) { return false; }

	// Verify that the ticket has not expired
	$ttl = $AUTHENT_CONFIG['ttl']; // integer seconds
	$expiry = strtotime($time_issued) + $ttl;
	$now = time();
	if ($expiry <= $now) { return false; }

	// If we're still here then the ticket is fine.
	return true;
}

8. Security through obscurity is no security at all.

If something isn’t secure from the people who built it then it’s not secure at all. Any conceivable attack by a non-trusted individual should be expected to take at least as long as a brute-force, try-every-possible-combination-in-sequence attack. The short lesson is don’t design a system to protect information yourself, that’s what the experts are for.

Let’s use the example of a naive web developer trying to protect the contents of a string in transit from a user’s browser to the server[1]. The concern, that someone might be eavesdropping on an intermediary computer, is a legitimate one.

Using obscurity, the naive developer might reverse the string of text so that it reads backwards or might be tempted to simply encode[2] the information using base64. They might even get creative and reverse the base64 encoded version of the reversed string. Certainly this information is going to be un-intelligible to any human who doesn’t know the “secret” method, but trivial to undo for anyone who does.

The simple fact that knowing the strictly the method allows someone to obtain the sensitive data means there is no real security here, only false hope. At minimum the method should make use of some secret information (that is not part of the message) but is previously known by both parties, a pass phrase in a symmetric cryptographic cipher for example.

[1] Obviously, the correct security method for this application is SSL.

[2] Encoding and encrypting are NOT synonyms.

9. KISS: Start Simple. Enhance Later.

A lesson we’ve adopted from the Web 2.0 crowd of beta-labeling fanatics. Start small, build only the minimum set of features you need and then extend the project later using client, peer and user feedback.

Obviously waiting for visitor feedback doesn’t apply to client-driven projects since they usually have a grand vision and talking them into a phased-launch approach is nearly impossible. However we can still apply this basic rule and build the complete core set of functionality before going back and adding “gee-whiz-bang” features like ajax to the UI.

The benefit is that we are able to see a working “big picture” application earlier, impress the client with the relative speed then go back in and add polish to the interface as needed. We can identify flow problems earlier, ideally before they become barriers to success and we can avoid over-engineering solutions to problems that really only exist in our imaginations.

10. Use the team. We’re on your side.

The last rule is one that is less about programming and more about corporate culture. The basic idea is that there are no stupid questions. We’ve assembled a very diverse team and each of us has different skills and specialties. No one person can ever be expected to know everything about internet software development, the body of knowledge is simply too big. Therefore we’ve spread the responsibility out over a dozen or more people (so far) and we need to work as a team.

If asked a question that you can authoritatively answer, do. If you have an informed guess then try (but let the asker know it’s a guess). When all else fails think about who else on the team might know better and re-direct the question.

The second part is that asking for a second pair of eyes to look over some frustrating piece of code will often make your own eyes work better. Either by talking through the logic (out loud) or by having a flaw in your logic pointed out the frustration often vanishes. Never feel stupid or ashamed for having not seen the problem yourself, it happens to all of us more often than we’d like to admit. Ask, fix and get on with the fun stuff.