Comments and indentation | PracticalSeries: Web Development

6.9 Comments & indentation

When I first left university and started writing software (sometime in the 1880s) I was working for the National Nuclear Corporation (it designed and built nuclear power stations—you don’t get company names like that anymore) and I was taught that it should take as long to comment your code as it did to write it in the first place—for any engineers reading this it’s still a good rule of thumb.

I take the view that all engineering software should be documented and self-explanatory; it should be commented to the extent that a competent person can understand the purpose of the software, how it works and the mechanisms it uses. Well documented code looks like Figure 6.21^†1.

Figure 6.21 - Documented engineering software

Engineering software, particularly that written for the pharmaceutical industry, is written to certain standards—specifically GAMP5 (Good Automated Manufacturing Practice) and IEC-61131-3 (International Electrotechnical Commission standard for: Programmable controllers—Part 3: Programming languages) and these insist on a good level of documentation, the use of mnemonics and revision control.

Now all the code written so far has been notably lacking in comments (breaking all my own rules), but that’s not because HTML and CSS don’t support comments, they do, it’s just that up to this point I’ve been lazy.

HTML and CSS (and Java script and jQuery) all support the use of comments (although for reasons that escape me, they do this in different ways) and I think the use of comments is encouraged in web development circles (I’m not 100% sure of this though, probably because it’s just extra stuff for the browser to load, see § 6.9.4).

I make extensive use of comments; I suggest you do too—particularly whilst you are developing 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.

6.9.1 HTML comments

HTML comments start with  anything in between is considered to be a comment and is ignored by the browser. Comments can span any number of lines.

There are some restrictions; HTML code can be officially validated by using the validation tool provided by the W3C standards organisation^†2. To use the validator just select the HTML code in Brackets and paste it in to the box on the validator web page here, click the check button and it will give a list of the errors and non-compliances in the code (that’s not to say the code won’t work, just that it’s not following best practices).

Now if a comment contains two or more dashes in a row after the initial <!--, the validator will complain about it, it will produce the warning:


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

Now this is just a warning (I think about converting the file to XML, which we don’t want to do) and has no impact on the way the HTML works, but it is irritating when you’ve used it all over the place and then you get a bag full of warnings every time you validate your code.

Why is this a problem? You ask; well it’s because you may make the same mistake I did when I started all this, I used a line of dashes across the page like this:


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

I used it as a simple divider, highlighting different sections of the HTML code. I did it all over the place—it’s how I started commenting the code, then I discovered the validation site, saw all the errors and realised I’d been doing it wrong and had to change it all.

This is a couple of extracts from an HTML page within the main website; you can see how I’ve commented it.

Figure 6.22 - Comments at the start of an HTML file

The first image (Figure 6.22) shows the start of the HTML file, you can see the first line is the <!DOCTYPE html> element. The second image (Figure 6.23) shows a section of the HTML further down the file.

I use a row of asterisks to indicate the start of a major section (usually with a title line followed by a second row of asterisks). I use a row of equal signs to indicate the end of a section; and I use a row of tilde characters (~) for minor sections and subsections. Minor sections and subsections usually have a title row followed by second row of tildes and a single row of tildes indicates the end of the section.

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 engineering school.

Now look again at the start of the HTML page (Figure 6.22)—it’s impressive I know (bet that’s not what you were thinking—you were thinking “now look what the idiot’s done.”).

Ok, I’ve treated this like I would an engineering project and included revision information; it’s how I keep track of the website whilst I develop it. The current version of that particular page is P01.04. The index.html page lists all the revisions made to any page on the website and its revision number shows the current highest revision of the whole website.

The sad thing is: I’ve got copies of every revision—that’s the next thing they teach you at engineering school: up-rev frequently and always make a backup (preferably on more than one hard drive).

I’ve put a lot of comments into the HTML—it’s extravagant I know, but this is a teaching website so the more the merrier.


†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.

6.9.2 CSS comments

CSS comments are cosmetically different to HTML comments, but they work in much the same way. CSS comments start with a /* and end with */, anything in between is a comment. Like HTML comments, CSS comments can span any number of lines.

CSS comments don’t have the same double dash restrictions as HTML comments; it’s perfectly acceptable to have a line of dashes in a comment:


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

Here is an extract from the style.css file used on the main website (Figure 6.24); it is this CSS file that contains the standard set of styles used on every page of the website.

Figure 6.24 - Comments from within a CSS file

I use the comment section at the start of the CSS file (Figure 6.25) in much the same way as the HTML file; it contains a description and revision history. With the CSS file I also use it to store a list of the colour values used throughout the website (it’s the COLOURS IN USE section in the comments). This is useful and saves you having to search the whole file to find the colour used for a particular item, see § 7.4.1.

Like HTML comments, I use a row of asterisks to indicate the start of a major section (usually with a title line followed by a second row of asterisks). Instead of the tilde character, I use a row of dashes (-) for minor sections and subsections. Minor sections and subsections usually have a title row followed by second row of dashes.

Figure 6.25 - Comments at the start of a CSS file

6.9.3 JavaScript and jQuery comments

This is easy; JavaScript and jQuery comments are the same as CSS.

Here is an extract from one of my jQuery files (can’t have too many brackets and braces in JS):

6.9.4 Comments—the downside

I like comments, they’re useful and it’s been deeply ingrained in me from a young age that they should be used extensively—use them young Skywalker—use them wisely.

Now, the problem with comments 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 download them and this in turn slows down the website.

This probably doesn’t matter too much on most websites, a few lines of comments in a page won’t make much difference one way or the other. My pages however, tend to be very well commented indeed; my philosophy is to spend as much time commenting code as I did writing it; my comments are extensive (and a pleasure to read I am sure), I comment like there is no tomorrow.

I did a quick experiment; the size of the finished style.css file is 73.0 KB. If I strip out all the comments, this comes down to 23.9 KB—that’s quite some saving (66%).

I’m not going to apologise about my comments and I’m not going to take them out, this is a teaching website and, in my view, the usefulness of the comments outweighs any hit the site might take on load time.

I advise you to use comments too, at least in the offline version of the site (the copy you keep on your computer). The online version (the one that gets uploaded to the webserver) can have the comments stripped out. This process is called “minimisation” and there are websites that do it for you:

6.9.5 Minimisation

Minimisation is the process of removing nonessential items from HTML, CSS and JavaScript/jQuery files. At the most extreme it strips out absolutely everything that is not need (including line breaks and unnecessary spaces).

Here is an extract from style.css with maximum minimisation (maximum minimisation—ha!):

The highlighted bit in the middle (.title-row) is the same section of code as that shown in Figure 6.24 (line 533).

It’s completely unintelligible; but it has brought the file size down to 19.8 KB (that’s a 73% reduction from the original 73.0 KB).

There are a lot of websites that do this minimisation, I use csscompressor.com, just select the code in Brackets, copy it and past it into the box on the website, select the degree of minimisation you want in the compression level box and click compress, copy the output and paste it into a new file in Brackets.

The convention with CSS and Java files is to add .min to the filename, so the minimised form of style.css would be called style.min.css.

HTML can also be minimised, this is a site that does it kangax.github.io. Opinion seems to vary on whether HTML should be minimised, however, 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 minimisation, make sure you keep an un-minimised copy offline somewhere.

6.9.6 Indentation

Indentation (the practice of indenting code further across the page) is used to make the code more legible. It works like this: in HTML, where elements are nested inside other elements, the nested elements are indented.

Brackets automatically indents nested elements (by default, each indentation pushes the text four spaces to the right). It looks like this:

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

Brackets indents by four spaces for each level, the W3C standard says two spaces, but I’m sticking with Brackets, I think it looks better.

It does get a bit silly after a while, with everything shifted over to the right. There is some room for compromise, I think it would be OK to not indent the <body> and <head> elements, just about everything else is embedded in these tags and I think it can be taken for granted that there is an implied indent. It looks like this:

Figure 6.29 - Slightly optimised HTML indentation

CSS is a bit different, the only thing that gets indented are declarations inside braces that span multiple lines:

JavaScript and jQuery also have indents, these are just like CSS; I discuss this further in section xxx.