2005-12-15: griffith news goes open source

Open source software can make it through the rigours of policy and procedure in a large organisation. Griffith University news (www.griffith.edu.au/news) is published using an installation of TikiWiki (an open source wiki/cms/groupware solution). The wiki not only delivers the articles, it generates the XML newsfeed.

A small win, perhaps... but it all helps.

[Disclosure: I work for Griffith and my team pushed for the wiki :) Most of the credit goes to Colin Morris. I worked on Wiki templating for this and other Tikiwiki installations at Griffith. Naturally the look and feel was decided by the internal client; and like most open source products I've worked with so far the default templates are table-based so it's taking a while to knock the templates into some decent shape.

Obvious disclaimer: this site does not express any views of the University, etc etc.]

2005-12-07: ozewai 2005 presentation

I'm delivering a short paper presentation at OZeWAI 2005 today, via Skype. The topic is "Sticks, Carrots & Staying Sane - an approach to standards advocacy in large organisations". You can view the presentation notes if you so desire! If you have any comments on the presentation, please post them here.

Tags: , , , , , , , , , , .

2005-12-03: xhtml and css code commenting

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.

2005-12-01: konqueror passes acid2 css test

Quick notable: Konqueror has passed Acid2. K Desktop Environment - KDE 3.5: A Visual Guide to New Features: Konqueror has now become the second browser to pass the arduous 'Acid2' css compliance test. Apple's Safari browser was the first, which makes use of Konqueror's advanced rendering engine KHTML.

Here's hoping we don't have to wait too long for the next browser to pass the test :)

It's worth mentioning that Opera 9 looks likely to pass Acid2: Opera 9, Acid2 and Web Forms 2.0.

Tags: , , , .

Blog Archive