6The CSS box model

When I first left uni­ver­sity and started writ­ing soft­ware (some­time in the 1880s) I was work­ing for the Na­tional Nu­clear Cor­po­ra­tion (it de­signed and built nu­clear power sta­tions—you don’t get com­pany names like that any­more) and I was taught that it should take as long to com­ment your code as it did to write it in the first place—for any en­gi­neers read­ing this it’s still a good rule of thumb.

I take the view that all en­gi­neer­ing soft­ware should be doc­u­mented and self-ex­plana­tory; it should be com­mented to the ex­tent that a com­pe­tent per­son can un­der­stand the pur­pose of the soft­ware, how it works and the mech­a­nisms it uses. Well doc­u­mented code looks like Fig­ure 6.21^†1.

Figure 6.21   Documented engineering software

En­gi­neer­ing soft­ware, par­tic­u­larly that writ­ten for the phar­ma­ceu­ti­cal in­dus­try, is writ­ten to cer­tain stan­dards—specif­i­cally GAMP5 (Good Au­to­mated Man­u­fac­tur­ing Prac­tice) and IEC-61131-3 (In­ter­na­tional Elec­trotech­ni­cal Com­mis­sion stan­dard for: Pro­gram­ma­ble con­trollers—Part 3: Pro­gram­ming lan­guages) and these in­sist on a good level of doc­u­men­ta­tion, the use of mnemon­ics and re­vi­sion con­trol.

Now all the code writ­ten so far has been no­tably lack­ing in com­ments (break­ing all my own rules), but that’s not be­cause HTML and CSS don’t sup­port com­ments, they do, it’s just that up to this point I’ve been lazy.

HTML and CSS (and Java script and jQuery) all sup­port the use of com­ments (al­though for rea­sons that es­cape me, they do this in dif­fer­ent ways) and I think the use of com­ments is en­cour­aged in web de­vel­op­ment cir­cles (I’m not 100% sure of this though, prob­a­bly be­cause it’s just extra stuff for the browser to load, see § 6.9.4).

I make ex­ten­sive use of com­ments; I sug­gest you do too—par­tic­u­larly whilst you are de­vel­op­ing the site. Let’s look at how to do it—HTML first:

†1		This is code written for my day job—it is statement list (STL) code for a Siemens Simatic S7-300 programmable logic controller (PLC)—an industrial control system.

HTML com­ments start with <!-- and they end with --> any­thing in be­tween is con­sid­ered to be a com­ment and is ig­nored by the browser. Com­ments can span any num­ber of lines.

There are some re­stric­tions; HTML code can be of­fi­cially val­i­dated by using the val­i­da­tion tool pro­vided by the W3C stan­dards or­gan­i­sa­tion^†2. To use the val­ida­tor just se­lect the HTML code in Brack­ets and paste it in to the box on the val­ida­tor web page here, click the check but­ton and it will give a list of the er­rors and non-com­pli­ances in the code (that’s not to say the code won’t work, just that it’s not fol­low­ing best prac­tices).

Now if a com­ment con­tains two or more dashes in a row after the ini­tial <!--, the val­ida­tor will com­plain about it, it will pro­duce the warn­ing:

	The document is not mappable to XML 1.0 due to two consecutive hyphens in a comment.

Now this is just a warn­ing (I think about con­vert­ing the file to XML, which we don’t want to do) and has no im­pact on the way the HTML works, but it is ir­ri­tat­ing when you’ve used it all over the place and then you get a bag full of warn­ings every time you val­i­date your code.

Why is this a prob­lem? You ask; well it’s be­cause you may make the same mis­take I did when I started all this, I used a line of dashes across the page like this:

	<!-- -------------------------------------------------- -->

I used it as a sim­ple di­vider, high­light­ing dif­fer­ent sec­tions of the HTML code. I did it all over the place—it’s how I started com­ment­ing the code, then I dis­cov­ered the val­i­da­tion site, saw all the er­rors and re­alised I’d been doing it wrong and had to change it all.

This is a cou­ple of ex­tracts from an HTML page within the main web­site; you can see how I’ve com­mented it.

Figure 6.22   Comments at the start of an HTML file

The first image (Fig­ure 6.22) shows the start of the HTML file, you can see the first line is the <!DOC­TYPE html> el­e­ment. The sec­ond image (Fig­ure 6.23) shows a sec­tion of the HTML fur­ther down the file.

I use a row of as­ter­isks to in­di­cate the start of a major sec­tion (usu­ally with a title line fol­lowed by a sec­ond row of as­ter­isks). I use a row of equal signs to in­di­cate the end of a sec­tion; and I use a row of tilde char­ac­ters (~) for minor sec­tions and sub­sec­tions. Minor sec­tions and sub­sec­tions usu­ally have a title row fol­lowed by sec­ond row of tildes and a sin­gle row of tildes in­di­cates the end of the sec­tion.

Figure 6.23   Comments from a subsequent section of the HTML file

Over the top you might think, but that’s what they teach you at en­gi­neer­ing school.

Now look again at the start of the HTML page (Fig­ure 6.22)—it’s im­pres­sive I know (bet that’s not what you were think­ing—you were think­ing “now look what the idiot’s done.”).

Ok, I’ve treated this like I would an en­gi­neer­ing pro­ject and in­cluded re­vi­sion in­for­ma­tion; it’s how I keep track of the web­site whilst I de­velop it. The cur­rent ver­sion of that par­tic­u­lar page is P01.04. The index.​html page lists all the re­vi­sions made to any page on the web­site and its re­vi­sion num­ber shows the cur­rent high­est re­vi­sion of the whole web­site.

The sad thing is: I’ve got copies of every re­vi­sion—that’s the next thing they teach you at en­gi­neer­ing school: up-rev fre­quently and al­ways make a backup (prefer­ably on more than one hard drive).

I’ve put a lot of com­ments into the HTML—it’s ex­trav­a­gant I know, but this is a teach­ing web­site so the more the mer­rier.

†2		The World Wide Web Consortium (W3C) was founded by Tim Berners-Lee and is the international body that produces the standards for the World Wide Web.

CSS com­ments are cos­met­i­cally dif­fer­ent to HTML com­ments, but they work in much the same way. CSS com­ments start with a /* and end with */, any­thing in be­tween is a com­ment. Like HTML com­ments, CSS com­ments can span any num­ber of lines.

CSS com­ments don’t have the same dou­ble dash re­stric­tions as HTML com­ments; it’s per­fectly ac­cept­able to have a line of dashes in a com­ment:

	/* ---------------------------------------------------- */

Here is an ex­tract from the style.​css file used on the main web­site (Fig­ure 6.24); it is this CSS file that con­tains the stan­dard set of styles used on every page of the web­site.

Figure 6.24   Comments from within a CSS file

I use the com­ment sec­tion at the start of the CSS file (Fig­ure 6.25) in much the same way as the HTML file; it con­tains a de­scrip­tion and re­vi­sion his­tory. With the CSS file I also use it to store a list of the colour val­ues used through­out the web­site (it’s the COLOURS IN USE sec­tion in the com­ments). This is use­ful and saves you hav­ing to search the whole file to find the colour used for a par­tic­u­lar item, see § 7.4.1.

Like HTML com­ments, I use a row of as­ter­isks to in­di­cate the start of a major sec­tion (usu­ally with a title line fol­lowed by a sec­ond row of as­ter­isks). In­stead of the tilde char­ac­ter, I use a row of dashes (-) for minor sec­tions and sub­sec­tions. Minor sec­tions and sub­sec­tions usu­ally have a title row fol­lowed by sec­ond row of dashes.

Figure 6.25   Comments at the start of a CSS file

This is easy; JavaScript and jQuery com­ments are the same as CSS.

Here is an ex­tract from one of my jQuery files (can’t have too many brack­ets and braces in JS):

Figure 6.26   Comments in a jQuery file

I like com­ments, they’re use­ful and it’s been deeply in­grained in me from a young age that they should be used ex­ten­sively—use them young Sky­walker—use them wisely.

Now, the prob­lem with com­ments in HTML and CSS is that they are stored in the HTML and CSS files, this makes the file sizes larger and that means it takes the browser longer to down­load them and this in turn slows down the web­site.

This prob­a­bly doesn’t mat­ter too much on most web­sites, a few lines of com­ments in a page won’t make much dif­fer­ence one way or the other. My pages how­ever, tend to be very well com­mented in­deed; my phi­los­o­phy is to spend as much time com­ment­ing code as I did writ­ing it; my com­ments are ex­ten­sive (and a plea­sure to read I am sure), I com­ment like there is no to­mor­row.

I did a quick ex­per­i­ment; the size of the fin­ished style.​css file is 73.0 KB. If I strip out all the com­ments, this comes down to 23.9 KB—that’s quite some sav­ing (66%).

I’m not going to apol­o­gise about my com­ments and I’m not going to take them out, this is a teach­ing web­site and, in my view, the use­ful­ness of the com­ments out­weighs any hit the site might take on load time.

I ad­vise you to use com­ments too, at least in the of­fline ver­sion of the site (the copy you keep on your com­puter). The on­line ver­sion (the one that gets up­loaded to the web­server) can have the com­ments stripped out. This process is called “min­imi­sa­tion” and there are web­sites that do it for you:

Min­imi­sa­tion is the process of re­mov­ing nonessen­tial items from HTML, CSS and JavaScript/jQuery files. At the most ex­treme it strips out ab­solutely every­thing that is not need (in­clud­ing line breaks and un­nec­es­sary spaces).

Here is an ex­tract from style.​css with max­i­mum min­imi­sa­tion (max­i­mum min­imi­sa­tion—ha!):

Figure 6.27   Minimised CSS

The high­lighted bit in the mid­dle (.title-row) is the same sec­tion of code as that shown in Fig­ure 6.24 (line 533).

It’s com­pletely un­in­tel­li­gi­ble; but it has brought the file size down to 19.8 KB (that’s a 73% re­duc­tion from the orig­i­nal 73.0 KB).

There are a lot of web­sites that do this min­imi­sa­tion, I use csscompressor.com, just se­lect the code in Brack­ets, copy it and past it into the box on the web­site, se­lect the de­gree of min­imi­sa­tion you want in the com­pres­sion level box and click com­press, copy the out­put and paste it into a new file in Brack­ets.

The con­ven­tion with CSS and Java files is to add .min to the file­name, so the min­imised form of style.​css would be called style.​min.​css.

HTML can also be min­imised, this is a site that does it kangax.github.io. Opin­ion seems to vary on whether HTML should be min­imised, how­ever, google think you should: developers.google.com.

• Minimising code improves the speed of the website, whether that’s important with today’s broadband speeds I’m not so sure. I do think however, that some sites minimise their code to make it harder for people to read and copy (just my opinion you understand—bet I’m right though).

I leave it up to you, but if you do use min­imi­sa­tion, make sure you keep an un-min­imised copy of­fline some­where.

In­den­ta­tion (the prac­tice of in­dent­ing code fur­ther across the page) is used to make the code more leg­i­ble. It works like this: in HTML, where el­e­ments are nested in­side other el­e­ments, the nested el­e­ments are in­dented.

Brack­ets au­to­mat­i­cally in­dents nested el­e­ments (by de­fault, each in­den­ta­tion pushes the text four spaces to the right). It looks like this:

Figure 6.28   Indented HTML

You can see how the start and end tags for each nested el­e­ment line up (the red lines show this).

Brack­ets in­dents by four spaces for each level, the W3C stan­dard says two spaces, but I’m stick­ing with Brack­ets, I think it looks bet­ter.

It does get a bit silly after a while, with every­thing shifted over to the right. There is some room for com­pro­mise, I think it would be OK to not in­dent the <body> and <head> el­e­ments, just about every­thing else is em­bed­ded in these tags and I think it can be taken for granted that there is an im­plied in­dent. It looks like this:

Figure 6.29   Slightly optimised HTML indentation

CSS is a bit dif­fer­ent, the only thing that gets in­dented are de­c­la­ra­tions in­side braces that span mul­ti­ple lines:

Figure 6.30   Indented CSS

JavaScript and jQuery also have in­dents, these are just like CSS; I dis­cuss this fur­ther in section xxx.