You are here:

Google's HTML/CSS Style Guide Is Really Awful

2/19/2014 08:46PM

Recently, a client asked if I could adhere to the Google HTML/CSS Style Guide for the HTML and CSS I am creating for their UI/UX. I had never heard of this guide before, and almost immediately saw the nastiness this would entail and wrote up the following as a thorough explanation of why I would be wasting so much time if I had to do this. They decided to go with my formatting instead. I think it is also quite telling that Google itself does not use their own HTML/CSS style guide!


First off, I use an incredibly easy to read and work with coding paradigm. It makes future changes and editing easy to do, and everybody that has ever looked at my code has commented on how clean and easy it is to read and work with, so I know that I am not just blinded by my preferences. I have been programming for over 20 years now, and have been able to get code maintainability and readability as the utmost importance.


So far as programming websites, I have been an advocate for XHTML and CSS since 2003, when we were just abandoning Netscape 4 (the last widely used browser with absolute crap for CSS support). So bear in mind that doing things the XHTML way are how I have done everything for over 10 years now.


I chose XHTML because it is more readable and restrictive than HTML. In HTML, you can be lazy and do things like this:

    <td><img src="dog.jpg"> My cool dog!


The XHTML way to do the same thing would be:

    <td><img src="dog.jpg alt="" /> My cool dog!</td>


Notice how everything has an ending tag, and control tags (such as the <tr>), which may be implicit in the <td>, are declared. Not that I use tables much any more due to heavy CSS, but it is the most obvious I can make this. By not having the ending sections, it is like removing all punctuation and capitalization to me when I read it.


Tell me which paragraph is easier to read:

four score and seven years ago our fathers brought forth on this continent a new nation conceived in liberty and dedicated to the proposition that all men are created equal now we are engaged in a great civil war testing whether that nation or any nation so conceived and so dedicated can long endure we are met on a great battlefield of that war


Or this one:

Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty, and dedicated to the proposition that all men are created equal.


Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. We are met on a great battlefield of that war.


This is further compounded because I need to constantly change and edit this content, and without points of reference, it is much harder to do so.


In short, my method of coding is done for the maximal readability and maintainability.


Google's recommended method of coding is for shortness, which is a huge mistake in my opinion. In fact, it is considered a huge mistake in a number of places by just about every programming format conceived. The phrase "premature optimization" comes to mind, because that is exactly what they are recommending. This leads programmers to saying, "premature optimization is the root of all evil" and they seriously mean it. 99% of the time, it achieves NOTHING POSITIVE and instead makes coding much much more difficult to read and maintain. Here is further information if you are curious: On Wikipedia.


Let's go through their document to point out the problems:


General Formatting Rules

Indentation - Indent by 2 spaces at a time. Don't use tabs or mix tabs and spaces.


I use tabs that are set to a 2 space indentation. I do not mix with tabs and spaces, but having to use spaces instead of tabs will muck up everything I do. If required to conform to this specification, I will likely use a separate editor, since using spaces in my own files instead of tabs will cause problems in the reverse. Oddly enough, tabs would also be smaller, so this is one of only two of their suggestions where the code gets bigger.


Capitalization - Use only lower case [...]


This would require me to do some oddly-specific things, largely to just make things harder for me to read, esp. in relation to colors. For HTML element names, attributes, etc, I always use lower case anyways because XHTML REQUIRES it that way. However, for my own code, this requirement is a killer. I do things in Happy Caps (also known as first caps camel case), where each word's first letter is capitalized. Going from class="SomeMenu" to class="somemenu" may seem marginal to the observer, but it means that I would have to learn a new format. It also makes things hard to read when EVERYTHING is lowercase.


General Meta Rules

Action Items - Mark todos and action items with TODO


Perhaps this matters collaboratively, but this is a silly requirement otherwise. I have my own "TODO"-style markers: KERBLUH; conforming to another method is just yet another thing to break me out of my coding habits. If I have to deal with someone else's code, great. Except even then, KERBLUH means it is MY issue to deal with, because nobody else is going to use it. At least, not up to this point.


HTML Style Rules

Document Type - Use HTML5 [it specifically says DO NOT USE XHTML]


Here is one of my biggest hang ups, esp. as I mentioned above with the readability. I have been using XHTML for over 10 years now. In comparison, HTML feels like a hack language, due to all the flaws and inconsistencies it allows in the code. It wouldn't be the hugest deal, except Google's spec here EXPLICITLY takes advantage of those flaws to make the code marginally smaller, and therefore making it darned-near unreadable for me. I feel like I'm translating from another language with the samples they give. Things like using <br> and not <br /> (the latter is the XHTML way) seems to be nit-picking.


Optional Tags - Omit optional tags


This is absolutely THE WORST ADVICE OF THE ENTIRE PAGE. Google even says that most web developers are typically taught not to do this. There is a good reason. Just like my lack of capitalization and punctuation above explains, that is how the code feels when you do not use optional tags. Secondly, while trying to code this way, you have to know every tag's optional vs not optional rulings, and in many cases, it is totally arbitrary. Looking at their "Not Recommended" sample, that is how I want to see code. If I saw what they have under their "Recommended" sample, I would feel that the person that coded that does not know what they are doing, or are a complete amateur. Google themselves ABSOLUTELY DO NOT follow this guideline themselves, probably because they know how darned-near impossible it is to maintain this formatting. This isn't even getting into the other issues you run into trying to do more layered HTML. Going back to the table sample above, if I didn't end that table and started another table, could you tell if that was another table INSIDE of the first table? Or was it another table that started after the previous one ended? How well can a human read without punctuation? How well do you think a computer can? Throw in trying to make anything work dynamically when you have to be aware of the last section before starting a new block, and suddenly you have complete disaster on your hands. Go to any professional website, Google included, and look at their source. They do not do this terrible, awful thing. This is premature optimization at its worst...


type Attributes - Omit type attributes for style sheets and scripts


This is thrown in there because HTML5's default for <script> is to use type="text/javascript", and its default for <style> is to use type="text/css". This will be great as soon as we don't care about browsers that don't have native HTML5 support, such as Internet Explorer 8. Once I can abandon IE8 and below, great (not sure if you knew, but Google abandoned IE8 a couple years ago and even IE9 support was dropped a couple months ago). Until then, I want my websites to work, not to enforce someone else's decision when to break things in some cases. As of now, IE8 is ~5-6% of all internet traffic. Unfortunately, I do mostly ecommerce sites. Putting off 5% of our customers on a $10m a month business is like tossing away half a million dollars a month. Why would we want to do this?


CSS Style Rules

Shorthand Properties - Use shorthand properties when possible.


Again, brevity over readability. Their sample with font makes it all too clear how hard it is to read. I do CSS3 all the darned time, and I had to look up what the heck 100%/1.6 does in a brief font tag. In the full version, it's completely clear what it is doing. For many CSS properties, I already do use short hand unless it is not clear, then I break it out. With proper CSS reduction, it can handle merging short hand attributes for me (the one I'm using now is simplistic for now). Again, this is a bad premature optimization requirement.


Leading 0s - Omit leading "0"s in values.


Another pointless optimization. We lose 1 byte in file size, and lose a lot in readability. By omitting a 0 for values in a limited, tiny range, we all of a sudden have a new format for numbers to appear in! So now you have your integer format ([0-9]+), floating point ([0-9]+.[0-9]+) and now a floating point between -1 and 1 (.[0-9]+). This also doesn't line up with other numbers very well. All-in-all, it makes it harder to read. To save a byte here and there.


Hexadecimal Notation - Use 3 character hexadecimal notation where possible.


Just another pointless optimization that makes things harder to read. What does color #F0F mean to you? If you put it into Photoshop, what happens? Does it give you #000F0F? Or #F0F000? It probably doesn't turn into #FF00FF, which is what it really means.


ID and Class Name Delimiters - Separate words in ID and class names by a hyphen.


This entire entry could have been omitted if they did not have the requirement for all lower case. So unlike almost all of the other odd-ball things they require, this one actually makes things LONGER. Instead of doing like I do with #VideoID, their recommendation is to do #video-id. Instead of .HomeMainMenu, they would do .home-main-menu. I have no idea what is more readable to normal people, but since I use dashes very sparingly (to separate sections instead of words), it is odd seeing the lower case with dashes way for me...


CSS Formatting Rules

Declaration Order - Alphabetize declarations.


I arrange my declarations by type, outermost first, innermost last. To me, it's thinking sequentially as we move into the content of the section. Like reading a book... it goes sequentially. Trying to make this alphabetic makes as much sense to me as alphabetizing a book makes sense. Not only that, but their sample is convoluted so similar things are actually together... when in reality, alphabetizing splits up related CSS parameters. For example, let's take a region with more than a couple parameters, and we would do something like:

.SomeRegion {
  position: absolute;
  left: 2em;
  top: 2em;
  z-index: 4;
  border: #000000 1px solid;
  background-color: #EEEEEE;
  padding: 10px;
  overflow: hidden;
  min-width: 1px;
  font-size: 120%;
  line-height: 1.4;
  color: #CC0000;
  text-align: center;


Reading through in this order, which makes sense to me, it tells me this region: Is positioned relative to its parent, at 2em from the left edge, 2em down from the top, on layer 4 from the bottom. It has a 1px black border with a light grey background (#EEEEEE), 10 pixels around the border as padding, and it is using clearfix (what the overflow and min-width mean). The text has a font size of 120% of the parent, a line height of 1.4 (or 140% of the base height of the font) and a color of dark red (#CC0000) and it is centered.


Google's style guide would have it be:

.SomeRegion {
  background: #EEE;
  border: #000 1px solid;
  color: #C00;
  font: 120%/1.4;
  left: 2em;
  min-width: 1px;
  overflow: hidden;
  padding: 10px;
  position: absolute;
  text-align: center;
  top: 2em;
  z-index: 4;


It just looks like everything was shotgunned into random locations and the parameters that meant something together are much harder to read. This is further exacerbated by CSS attributes that BELONG together but have very different names (box-sizing, width, min-width, max-width, height, min-height and max-height as one list I'd put TOGETHER, but look at them alphabetically and they're a mess).


CSS Quotation Marks - Use single quotation marks for attribute selectors and property values.


This is absolutely awful advice! Not only do some browsers not accept single quotation marks at all (I remember tearing my hair out trying to figure this out for old Mac IE), but some features of CSS don't even support them (they even bring up the @charset rule which doesn't permit them) and elsewhere, they say to always use double quotes in the HTML! So why have a different requirement in CSS vs HTML when there is no benefit, it doesn't change file size in any way, and it just makes it harder to look at?


Note that there are a number of things I skipped. The exact number of spaces to use between lines is actually less than I use for the most part, and is completely unlike my formatting. They only show a few comments and they are simplistic compared to what I use, and don't contain separators like mine do, which makes it significantly harder to visually see separate sections. Since I am running all of the final CSS through a filter, none of the spacing part even matters since it gets removed in the final result anyways...



In short, I definitely will NOT be using their guide for my code, and apparently, nobody else is either.