I often use the services of freelance web developers, who create documents or templates for projects, which typically I then modify.
I have put a lot of time and effort into selecting great freelancers; each of my suppliers produces excellent, valid HTML or XHTML and CSS. Over time, I have learned to make some key requests up front. When my suppliers apply the following tips, I find it much easier to understand and tinker with their code. I hope you find them useful too:
1. Begin the Document with Last Modified Details
Traditional software development has a developed a complex set of practices and procedures for
dealing with version control but web design documents are normally created, revised and shared in a much more casual manner.
I recommend using a short comment at the beginning of each document, noting who last modified it, and when. For example:
/*-------------------------------------------------
CSS Document for xyz.com
Last Modified by Michael Heraghty on 04 November 06
---------------------------------------------------*/
This last modified comment is particularly useful in CSS documents, as style sheets get changed more often than individual web pages.
Nevertheless, I like HTML documents to have a last modified comment, though I appreciate that it may not be practical, depending on what editor you use. (With Homesite, it's a snitch. Homesite is my editor of choice for many reasons; its powerful set of "Find and Replace" features among them.)
2. Indent the HTML Code Properly and Consistently
Most web designers worth their salt will nest their
HTML, but I reckon that at least 50% of the documents I receive from freelancers aren't properly and consistently indented.
Here is an example of what I consider to be HTML that's not properly indented:
<html>
<head>
<title>Sample document</title>
</head>
<body>
<div id="intro">
<p>Lorem ipsum dolor sit amet.</p>
</div>
<div id="main">
<ul>
<li>1st list item</li>
<li>2nd list item</li>
</ul>
</div>
</body>
</html>
And here's the same HTML, this time with what I consider to be proper indentation:
<html>
<head>
<title>Sample document</title>
</head>
<body>
<div id="intro">
<p> Lorem ipsum dolor sit amet.</p>
</div>
<div id="main">
<ul>
<li>1st list item</li>
<li>2nd list item</li>
</ul>
</div>
</body>
</html>
I use HTMLTidy, built-in to Homesite, to help with indentation.
Some will argue that the more indentation, the more whitespace and therefore the greater the file size. That's true, but I think the trade-off is worth it. The increase in file size is unlikely to be significant.
3. "Close" div and span Tags Using Comments
Did you notice the comments I added in the previous example?
I hate seeing end-div tags. I have to hunt for the opening div (that can be a real pain where the code hasn't been properly indented, or where divs with the same class occur several times in succession.
To avoid headaches, I request that freelancers put comments right after a closing div or span tag, indicating the name and type of the relevant selector. For example:
<div id="wrapper">
Lorem ipsum dolor sit amet.
<span class="intro">
Lorem ipsum dolor sit amet.
</span>< !-- .intro -->
</div>< !-- #wrapper -->
(Note: I had problems displaying comments here, so I had to add a space before the exclamation mark - don't do this in "real" code, or the comment won't be hidden.)
4. Use Breadcrumb-style CSS Selectors
One of the most difficult elements in reverse-engineering someone's code is figuring out where various
CSS selectors are used in the
HTML document.
I like my designers to get specific, wherever possible, when identifying selectors in documents.
For example, rather than:
.credit{
border: 1px solid #000;
}
I prefer to see:
#footer p.credit{
border: 1px solid #000;
}
Now I know the "credit" class occurs within a paragraph, nested within a footer div. I can "see" the HTML, even though I'm looking at the CSS. I also know that changing the "credit" class will affect the footer of the document, but no-where else.
My CSS editor of choice (Top Style Pro) groups selectors according to inheritances, so that I can see at a glance all the selectors that start with #footer. In other words, I can see all the footer CSS grouped together.
Purists will argue that this breadcrumb-type selector identification isn't efficient, since it adds extra bytes, and it probably isn't true to the "spirit" of CSS either. Again, I would argue that there's a trade-off between being pure and being practical, and you have to strike a balance.
5. Explain Your Hacks
You may have expected that I would want my freelancers to provide many clear comments in
XHTML. Truth is, so long as the designer has coded neatly and efficiently, and has had adhered to the tips I've already mentioned, I don't need to see many other comments. At that point, the
HTML and
CSS documents should be straightforward
*. In fact, commenting the obvious may be irritating.
CSS hacks are different, however. There is a large and still growing zoo of hacks for the various browser bugs. I don't intend to learn all of them, let alone try to keep up with them.
All I need to know is – what does your hack do? Often this simply means what browsers is it hiding from/visible to?
For example:
/* Hides from Firefox all versions/platforms \*/
/* Hides from IE5.x-windows \*/
*I also like to see clear and detailed comments when the document contains non-native code -- such as PHP, JavaScript, MT or Wordpress tags, etc. But I haven't dealt with this here as I'm concentrating specifically on (X)HTML/CSS.
