Writing legible code
Pounding out code that does what you want, more or less, is one thing. Writing clean, legible code is another. Legible code has a clear structure. It is easy (relatively speaking) to revise. Its pieces can be readily reused in other contexts. It saves labor and thought.
Closure
- Always close tags. When you write an opening tag, write the closing tag too. For example, if you’re putting in a link <a href="…>, it’s easy to forget the close quotes for the URL and the close tag </a> for the link. If you type <a href=""></a> immediately, then you don’t have to remember to finish the quotes and the tag. Not having to remember stuff is a good thing.
- The same in CSS. When creating a class in CSS, type the closing curly brace immediately. The same goes for attributes: if you type font-family: but you haven’t decided which font to use, type the semicolon (which is effectively the close tag for an attribute specification). Otherwise the browser is likely to ignore everything in the style sheet that follows.
.weirdstuff {font-family:;}
Comment copiously
The code in HTML for a comment is <!-- your comment here -->. That’s an exclamation mark and two hyphens. In CSS the code is /* your comment here */. Everything inside comment tags is ignored by the browser. It will, however, be visible to any user who views your source, so don’t put any embarassing secrets or libelous remarks in your comments!
Uses:
- Information about the document. You can include your name and so on, and (more importantly) a revision date. One good place to put this is immediately after the <title> of your document.
- Visual markers. Use something like <!-- ****************** --> to mark off sections of code (e.g. the beginning of the <body> in HTML.
- Identifying chunks. In some cases the opening and the closing tag of an item may be separated by lots of other stuff. This is true for the divs that define a two-column layout, or for the opening and closing of a list. It’s very helpful to add what in effect are your own “opening” and “closing” tags to items like this so that you know which closing </div> goes with which opening <div>. Otherwise, if a closing tag is inadvertently omitted (or a superfluous tag left in) you may have a hard time figuring out what went wrong. View the source for this page and you will see quite a few comments of this sort: every list, for example, including this one, has an opening and a closing comment that identifies it uniquely.
- Reversion. Sometimes you may make a change you’re not sure you’re going to keep. In order to make reversion to the former state of your document easy, rather than delete the code you’re replacing, put it inside a comment.
Recycle ruthlessly
The rule is: don’t invent anything twice if you can help it.
- Code snippets. In programs like MarsEdit and HyperEdit, you can create “snippets” and assign key-equivalents to them. A snippet is just a bit of text, typically code, that you are going to use again and again. For example, in this weblog and in Philosophical Fortnights, inset quotations have a style of their own <div class="inset">… </div>. I’ve made a snippet for this. It includes the close tag, so that in using the snippet I automatically adhere to the first rule above.
- CopyPaste. This is one of several programs that allows you to save clipboards. I use this constantly not only in writing code but in writing lecture notes and other documents in which the same structures appear again and again.
- Templates. Save and reuse an “empty” document if you’re going to be creating several of the same sort. I also have made a template for Philosophical Fortnights so that I can preview drafts without posting them.
