When writing code — HTML, CSS, PHP, Javascript, or whatever — it is important to remember that yourself and others will read and interpret that code again at some point. In addition to being free of syntax errors and bugs, your code needs to be human readable. Here are three fundamental graphic design principals that we can apply to writing code for web sites.
1. Organize your code into logical chunks, separated with line breaks and indented with tabs.
Line breaks and tabs are cheap in terms of disk space. Use them. When your code makes a shift from doing one thing to another, add a few line breaks to give the coder a mental break. And use tabs to indent loops and if/else statements. This may seem like common sense, but I’ve worked on a lot of code that looks like the original developer was trying to cram as much on one line as they could. Looking at a magazine for examples, you will see they group content into chunks, control line lengths to increase readability, and use indentation to denote new paragraphs. These are all good conventions to apply to your code. Here is an example in PHP:
/*
Comment each section of code so other developers know what you were doing.
Here is the first section of code
*/
if($request->getParam('f_title') != '') {
$item =& $controller->loadModel('Task', $request->getParam('f_ID'));
$item->setTitle($request->getParam('f_title'));
$item->save();
} else {
$renderer->setAttribute('t_error', true);
}
/*
The second section of code begins after an empty line, to differentiate it from the section above.
*/
$renderer->setTemplate('tasks/view.php');
return ACTION_NONE;
2. Separate your code into logical layers
A web site will have many different components: SQL code, business logic, and a HTML/CSS display. Think of each of these as a different design element. For example, when designing a magazine layout, you don’t put footnotes in the table of contents, and you make sure the photos belong to each article. You keep different content apart and similar content grouped together. When organizing the code for your site, keep the HTML and the SQL code apart. And keep the server-side code, like PHP, away from the CSS. Here is an example of how NOT to do it, using HTML, PHP, and SQL:
<!--Really bad way to do things. Is it HTML? Is it SQL? is it PHP?-->
<ul>
<?php
$sql = "SELECT * FROM list";
$res = mysql_query($sql);
while($arr = mysql_fetch_assoc($res)) {
?>
<li><?= $arr['text'] ?></li>
<?php
}
?>
</ul>
3. Use a good code editor with color coding and auto-indentation
The editor you use can make all the difference. A good code editor will color code different elements of code depending on their purpose. For example, we use Zend Studio, which makes comment tags a light gray and displays strings as green text. This denotes the comments so they aren’t visually interrupting my code-writing, while the coloring guides my eye to the specific portion of code I need to address. In the same way that a graphic designer will lead the reader using colors, the code editor can make your job of writing readable code much easier.
I know a few developers write code that no one can follow but these tips are kinda useless.
If your a designer thats trying to tell developers how to do their job really its not necessary. Nearly all developers care a great deal about the style of their code. Your not a developer if you haven’t been in an argument on whether to but the { on the next line or the same one.
In your first example you don’t indent the lines of code within the if { } else {} blocks. Practically every developers style guide for writing code ever says this is one of the key things to do.
Most developers have moved beyond using vi or emacs. In any case both of them can do all you suggest here and more things that you probably have never dreamed of like viewports, placemarks, folding and regular expressions. Emacs and vi make most “modern” editors look sparse. The lack of pretty buttons to point and click mean most people will never see these features and sadly never use them.
PS. I still use vi (well vim) its the best editor bar none and the years I have invested in learning it pay off every day.
Good point on the indents. I thought I’d caught that. WordPress isn’t very good at code formatting.
I have a minor in computer science and a bachelors in graphic design, but work primarily as a programmer now. So yeah, I am trying to tell developers how to do their jobs. You’d be surprised how many developers don’t pay attention to the style of their code. Lift the hood on a few open source web apps and you’ll see what I mean.
Vim is okay for minor edits and has saved me a few times when I needed to edit files quickly. Most of the web apps we build are not complex enough to warrant viewports, placemarks, or folding. We do rely heavily on regular expressions, but i’m still convinced they are voodoo.
I think you’re right. There are far too many people out there writing code without a clue how to write code properly. WordPress is a perfect example (yes, that was a burn). These simple tips are the bare minimum and it’s probably a great start for this audience.