Good programming habits make good markup habits too. A few well-placed XHTML and CSS comments can save you a lot of time later on and help your coworkers pick up where you left off... just as it does for programmers!

Complex <div>-based designs can be hard to navigate once the real content is inserted - you find yourself wondering what a specific </div> is actually closing. Even with your text editor's Nifty Bracketing Feature™ it can be time-consuming, plus if you've put a </div> in the wrong place in template-driven site the bracketing might be out of whack anyway.

Garrett Dimon: Closing Divs offers one suggestion which is close to what I've been doing for quite some time now. From the comments it seems a lot of people are yet to embrace code commenting; so I thought I'd show my system as an alternative. No doubt I'm not the only one out there doing this :)

comment your closing elements

I'd say comment your </div>s but sometimes it applies to other elements. No big trick, just put a comment after the closing tag including the id or class name of the element being closed:

<div id="content">
...
</div><!-- end #content -->

Obviously you could leave out the end - you know it's ending something since it's a closing tag - but a tired mind will appreciate the plain English. Plus, if a less experienced developer does the update it will help get them up to speed.

Actually over time I've started leaving out the end; but it's still an option. More important is ensuring you put the comment on the same line as the closing element. It avoids confusion like this real code example I saw recently:

                      </div>

               </div>
        </div>
                                       </div>
                               </div>
<!-- END Content Division -->
                       </div>
<!-- END BOTTOM SECTION -->

Want to bet on which one is the end DIV for the section? :) Is the second comment simply informative, or is it labelling the previous DIV? To aovid confusion, put the comment on the same line and don't put any other elements on that same line.

Don't jam the class/ID name up to the comment though, since <!--# is used for SSIs, environmental variables and so on.

Also, don't use multiple dashes inside your comments. Although it might look good to use <-- ----- blah ----- -->, you'll find that some Moz/Gecko browsers interpret any instance of "--" as a closing HTML comment. That means the natty sets of dashes will close your comments and that will Break Stuff™.

indent nested elements

A no-brainer, surely. Indent by one tab for each nesting level:

<div id="wrapper">
    <div id="header">
        <h1>Page Title</h1>
    </div><!-- end #header -->
    <div id="content">
        <div class="post">
            <h2>Post title</h2>
            <p>...</p>
        </div><!-- end .post -->
    </div><!-- end #content -->
    ...
</div><!-- end #wrapper -->

Indenting is not exactly a form of commenting so much as formatting; but it does lay the groundwork for some further commenting later.

css loves comments too

A few well-placed comments in your CSS can save a lot of headaches later on. A quick reminder about the order and nesting of id/class elements will save you reverse engineering that site you published a year ago, just to tweak a margin.

In fact, just separating the groups of definitions may be enough; eg:

/* ---- content ---- */
/* ---- links ---- */

...will help you find what you're looking for as quickly as possible.

If you're retrofitting an existing site, sometimes you won't have the chance to choose the markup; so you might need to remind yourself what's going on in the document:

/* .breadcrumb applies to DIV or P depending on the template */
.breadcrumb {
...
}

I know you'd rather get out there and standardise those templates; but right now, give yourself a break and comment that gotcha :)

If you're handing over a particularly complex design to somebody else, you might throw in an outline:

/* element order:
div#wrapper
  div#header
 h1
  /div#header
  div#content
 div.post
  h2
  p
 /div.post
 div.comments
  p
 /div.comments
  /div#content
  div#navigation
 h2
 ul
  /div#navigation
  div#footer
 p
  /div#footer
/div#wrapper
*/

Some may find this too much bloat for the stylesheet, but a little bloat may be a small price to pay for faster updates. It depends on your priorities. You could put the outline into separate documentation, but how many of us store our documentation as reliably as we store the actual sites? Be honest, now :)

brute force versions

If you're not using a full-featured versioning system like SVN, you can still do some basic version tracking. I find this especially useful for CSS, which tends to be tweaked relatively frequently. A simple number and date will do:

/* v1.1.8 - 2005.11.05 */

Use the appropriate number of version levels for the given site. I've found three levels works for me: a tweak is n.n.n+1; addition of elements and so on get n.n+1; whole new designs are n+1. If you're really keen, working copies can have n.n.nx where x is a-z; eg. 1.1.7a, 1.1.7b. Update the version when you upload to your server. Simple.

don't go crazy

Not everything needs to be commented. In fact, some designs are so simple you don't need to do it. If the closing tag is and will always be within a couple of lines, then common sense says you don't really need to comment it (unless you're into a serious debug exercise). But if the design is complex, or you regularly pass work around within a team or even to another team; then good commenting will help everyone.