It’s a common myth in some developer circles that good code is self documenting. Heck, I’ve seen thousands of lines of outrageously bad code and HTML without a single line of comments. When asking the original developer they will often tell you that their code is self documenting. This myth has been used as an excuse for not documenting code and HTML so many times that it literally makes me sick.
That’s why I want to take this opportunity to take a good look at this myth. However, allow me to introduce the HTML comment tag, then at least you can’t say you don’t know what it looks like or what it does.
It’s a really simple and easy to use tag. Even more importantly the information you provide in between the start and end comment tag can save yourself and the next developer who is looking at your HTML a ton of time!
The Myth About Self Documenting Code
Myth: Good code is self documenting and does not need comments or other sources of documentation.
Demystifying the myth: To some extent it is true that code is self explanatory. The assumption is that if you write good, elegant HTML code it will be easy to see what you’re doing.
Back when the first programming languages where invented the syntax made it difficult to read what the intention was. These days you can read the code of the most common programming languages pretty much as if it was plain English. This goes for HTML code as well. Although you can’t read it as if it was a novel it’s fairly easy to discern what each HTML tag does. In other words the code is self documenting.
Each line you read tells you exactly what it does and that has led the more laid back (lazy) developers among us to conclude that there is no need to actively document code.
Debunking the myth: I have yet to see an HTML source code file online that is less than 100 lines long. In fact, the Google main page, which is basically a text field and 2 buttons, is more than 200 lines long if you look at the source code.
With that many lines you simply need to be able to get a good overview of the HTML code as fast as humanly possible! Commenting your HTML is the best way to do that!
It is true that you can see what each line of HTML does, but comments are there to help you quickly understand what the entire HTML page does!