Google HTML /CSS Style Guide Review

HTML

? Omit the protocol from embedded resources. 
? Indent by 2 spaces at a time.
? Use only lowercase.
? Remove trailing white spaces.
? Use UTF-8 (no BOM).
? Explain code as needed, where possible.
? Mark todos and action items with TODO.
? Use HTML5.
? Use valid HTML where possible.
? Use HTML according to its purpose.
? Provide alternative contents for multimedia.
? Separate structure from presentation from behavior.
? Do not use entity references.
? Omit optional tags (optional).
? Omit type attributes for style sheets and scripts.
? Use a new line for every block, list, or table element, and indent every such child element.
? When quoting attributes values, use double quotation marks.

In order to remain consistent across all languages and platforms, 4-col tabs should be used.

TODOs have nothing to do in the markup. Task management is a good thing, do it.

Since HTML is bound to be semantically incomplete, a line must be drawn. I draw it after div,p,li,span,a,h1.

Omitting optional tags is murder. One does not simply self-close tags. (optional tags are inconsistent, break XML compatibility and thus many HTML parsing tools, just to save a few characters)

Consistency > all, and if you're going to pick only one quotation style, pick the same for CSS and HTML

CSS

? Use valid CSS where possible.
? Use meaningful or generic ID and class names.
? Use ID and class names that are as short as possible but as long as necessary.
? Avoid qualifying ID and class names with type selectors.
? Use shorthand properties where possible.
? Omit unit specification after “0” values.
? Omit leading “0”s in values.
? Use 3 character hexadecimal notation where possible.
? Prefix selectors with an application-specific prefix (optional).
? Separate words in ID and class names by a hyphen.
? Avoid user agent detection as well as CSS “hacks”—try a different approach first.
? Alphabetize declarations.
? Indent all block content.
? Use a semicolon after every declaration.
? Use a space after a property name’s colon.
? Use a space between the last selector and the declaration block.
? Separate selectors and declarations by new lines.
? Separate rules by new lines.
? Use single quotation marks for attribute selectors and property values.
? Group sections by a section comment (optional).


The only standard that works across everything, from SQL to Shell to any language, is underscores. Since technology is mostly about linking technologies, incompatibility for no reason is unacceptable.

I'll use spaces when I want to. Useless spacing left and right serves no purpose, unless you're using a broken font to edit code with.

Then back to the single/double quotes discussion.

Conclusion

Overall, the google style guide for HTML/CSS is not half-bad, but it makes critical mistakes on the consistency side (underscores, quotation marks and indentation).


I'll finish with their own:

Parting Words

Be consistent.

If you're writing a coding style guideline, focus on consistency above everything else.

REST (for the web), explained and reviewed

REST is about using HTTP features when they exist and serve your purpose.

URI (Uniform  Resource Identifier)

Don't: 

https://www.myapi.com/api/edit/user/3

.../api/read/user/3

.../api/users/frank/user/3

Do:

.../api/user/3

HTTP Methods

Don't:

.../api/user/create

.../api/user/3/edit

.../api/user/3/read

.../api/user/3/delete

Do:

HTTP PUT .../api/user

HTTP POST .../api/user/3

HTTP GET .../api/user/3

HTTP DELETE .../api/user/3

Multilingual content support

We want to keep the URI unique, so:

Don't:

.../api/blog_post/3/fr
.../api/blog_post/3/en

Do:

Use the language header in your GET request:
.../api/blog_post/3

Accept-Language: da, en-gb;q=0.8, en;q=0.7

Hypermedia (HATEOAS)

The idea here is that you wan't to specify all possible actions within the HTTP answer and as Hypertext, rather than have the application generating them based on external (to the request) information.

Don't:

Add a Save button because you just created an edit form.

Do:

Add a Save button because GET: .../api/post/3 contained the information for that, e.g. (in XML for clarity):

<action link='https://www.myapi.com/api/post/3' method='POST' name='Save'>

This is still unclear to me (and it would seem, to everyone who blogs about it), but it may be that the only practical way to implement a so-called "Hypermedia API" is just a plain old website, with API structure and URLs.

Representation

The URI is unique, but the representations are many.

You should specify the representation using Accept headers like so:

Accept: application/json

for standard application requests,

Accept: text/html

for basic/crawler requests, or even

Accept: application/xml

if you have customers with an XML security filter.

Self-Description

The vision is that you should be able to get all the relevant information for API use from the API itself, and the proposed solution is to use media-types for that (application/myapplication+json or application/json;app=myapplication).

I haven't found anything relevant on this topic so far, meaning that while some people have some approaches to the solution, nobody seems to have a standardized clean and simple way to do media-types.

In other words, create your own media-types, stay tuned for news, keep it simple, make sure your own application gets the meta-information from the HTTP response, rather than from your code.

Architecture Constraints

Captain Obvious to the rescue:

Client/Server: the Server only acts as a Server, it does not hold state.

The Server stores no client state (things that can make the application behave differently, outside of session id and authorizations)

Cacheable: do set your cache headers.

Layered System: whatever the infrastructure, the client cannot tell the difference and sees only an endpoint

Code on demand: you can include .js files in your /js directory !

Uniform Interface: keep it standard and simple thanks to the points above.




Ok so now you know what REST is. Time to review the concept:

The good

One of the objectives is to make web services as straightforward and self-descriptive as possible, using existing tools where they fit the bill.

Self-Descriptive services are awesome, and using media types for that sounds like a good idea.

The use of accept headers for language and type concerns sounds better than /en/ although that means changing languages should be made easy (I often edit URLs because the change language mechanism is either dozen-clicks or hard to find).

The bad

While there are enough HTTP methods to handle CRUD, that is not going to be enough for more advanced cases, as e.g. a "report" item, that requires CRUD + Run, making the use of HTTP methods as API methods a source of inconsistency.

Self-Descriptive services are awesome, but the REST architecture does not specify a standard for this, leaving everyone to do different incompatible things.

Because an API is a tunnel for a remote application to call local functions, the approach of Unique Resource Identification through URLs (i.e. /item/id/method)  is a leaky abstraction.

One of the problems is that it results in an Object Oriented API, with a much wider logical map, meaning that you will have a hundred (virtual or not, same problem for clients) create relation methods like object/id/relate/object2/id2 /object/id/relate/object3/id3, etc. instead of the single method approach like relate/object/object2/id/id2.

Another problem is that it implies inconsistency as non-resource methods won't fit in such a schema anyway (such as login, metadata (relations and items, rights) ), a bit like Java needs a container class to define a function.

It could work if you're only writing APIs with basic public resource access, but that isn't generic in any way.

In order to remain consistent, it is thus better to simply avoid the OO/REST API style altogether (unless you still believe in OO).

My Conclusion

REST has some good points and those are likely to be part of any good API architecture.

However, there are too many bad points to consider REST a valid API architecture, and only one practical good point, with Hypermedia that may or may not be a good point, depending on how the alternatives fare.

HATEOAS is a curious idea: on the one hand it means you need two representations for your API (you don't want the HREF overhead in your application), but on the other hand that secondary text/html hypermedia representation could serve API documentation purposes and maybe even crawling purposes.

It seems to me like a Hypermedia API simply means providing an html1.0 presentation for your API with  human-readable documentation associated with its text/html media-types.

It may have value but then they should've just called it that instead of adding more buzzwords.

Links

Concrete Example

REST / Headers

Something on Versioning and Headers

Roy's Thesis

One (imo wrong) way to self-describe

Invisible MMO cell boundaries

Imagine you're flying a space-capable plane, fighting enemies on the ground. (that's obviously one cell, managed by one server).

Then another aircraft starts chasing you and you decide to turn this into a space battle, knowing your faction has a much better advantage up there than down there (they moved a space battle station above the position they were attacking, but the ground forces of the enemy are still alive and kicking, for example). (the space will obviously be in another cell because it's so incredibly far, and contains it's own lot of objects and stuff).


Now in most games you'd climb and climb, and see a loading screen, then climb again.

That would make no sense at all from the perception of the aircraft in pursuit, and would break a lot of the immersion.


We need a solution without any loading screen or visible server switching to make this just awesome (imagine an aircraft chase from the ground into space, a space battle, and then the chase reverses as the hunter becomes the hunted, and flees down to the ground -- no interruptions, no loading screens, only amazing immersion).


For the server-side, I think the solution would be slightly overlapping cells, and silent connection to the next cell's server (servers actually because if you aim for the top corner of a cube you will be in a 4-cell overlap) at that point, tracking the aircraft and its projectiles in both grids.

The client would have a proper solution for dynamic loading of resources (a bit like a moving window concept) and would reconcile the inputs from multiple servers, discarding duplicate input (like when four cells track the same missile, only one collision will be recorded and the rest is safely discarded) and making a seamless transition between two cells, effectively creating an infinite immersion, no 1000m flight ceiling, no "go back to the combat zone", no crap.

If you want to take the 60 miles detour to attack from a better angle, suit yourself.
If you want to go from the planet to its moon in your little aircraft, suit yourself.

Code indentation

4-column tab

Consistency > your feelings about code indentation.





Spaces will never be consistent and require a lot of text-processing on commits and reads, etc. with no added benefit.

Tabs are semantically correct: one tab indents, where some number of spaces could mean anything.

When you set your own column width preference for tabs, the view is altered. This is logically correct.

When your editor transforms four-space-indents into 2-space-indents, the content is altered. This is incorrect.


8-cols are obviously a joke, as one can only imagine the result of 8-col tabs, 32-col TTY and 4 levels of indentation.

2-cols are rather unclear considering how people like adding "one space" everywhere for "clarity".

3-cols is not a power of 2, so it doesn't work.

4-cols is the best answer, it's both clear, not too wide and a power of 2.

Code Avengers Review

HTML track

level one

This is just horribly painfully slow, i.e. exactly what a real beginner will find welcoming and useful.

More than that, there's a focus on realistic training, making you check for common mistakes you (and I) make when writing HTML, and really going step by step.

If anything, I would've found it too slow when I was a beginner, but then that always was my reaction to any kind of teaching, so I think it must be just fine as is.

Then it introduces you to google fonts ! which is just awesome.

Then I even learned about stuff I had forogtten (text-shadow and multiple shadows) and never cared about (lists, header, footer) and probably never will use.

I must say my biggest surprise is that not a word was said about divs, and divs are about the only thing I ever use in html5 nowadays - but then they say that's for the level two course - let's see if they provide it for free to a reviewer ...

And then, some things went wrong, too:

• at 7.4, the instructions ask you to link to the Code Avengers home page when they actually mean to /home.html (i.e. not http://www.codeavengers.com) - sure some people may get it right, but I'm still angry.
• use of broken google web style guide: http://ludovicurbain.blogspot.be/2013/06/google-html-css-style-guide-review.html

JavaScript track

level one

Slow, but not as slow as the HTML one, I suspect they expect people to do HTML before JS, so that's only fair.

Very smart pedagogy, pushing you far into the problem to make you want the solution, long tutorial, with reviews and everything, really thorough and yet not annoying (except the "game" pauses... who wants to shoot dem satellites...).

Much more fluidity than Codecademy as well, going from one task to the next is much less disruptive, there are no interruptions between "topics" either, really immersive and enjoyable.

Excellent pedagogy again by not holding the user's hand while remaining clear and simple.

Also they make you test every code path EVERY time, bit annoying but really good practice, until they give you unit tests that largely speed up the process (probably intentional to make you want to have unit tests).

There's a strong focus on results, letting you use whatever means you feel fit to achieve the results, very flexible (actually what I expected from Codecademy).

And then, some things went wrong, too:

• 19.5: once again someone insists on using stupid broken two spaces tabs when the whole world has only one standard of four spaces tabs. Dear broken style standards, please die and let us have consistency at last.

Conclusion

This can't be final until I review their other courses, but right now I'd say that compared to Codecademy, they have a far uglier interface for the HTML, ok-ish for JavaScript, much better pedagogy and course quality, and I would not hesitate recommending them to newbies, for the HTML and JavaScript L1 course, with a mention to quickly forget the google style guidelines that were probably written by a team of drunken monkeys.

And while the interface may be a little bit less sleek, the pace, interaction and immersion is far better. You can literally sit at your computer for several hours just being in the zone learning the stuff.

The duration is fair, it took me a good two hours (writing this at the same time) for the HTML 1, 4 hours for the JS 1, when it's marked at 10 and 20 hours respectively for newbies - so really fair, probably 10 to 30% above average for newcomers.

All in all, if you're going to learn js or html, go to www.codeavengers.com, it's simple and a great start, at least for the first free level (didn't get a review token for the rest yet).

so @codeavengers, great job guys, time to expand, and please let that google retarded web style die, it's really not in the same class of quality as your teaching service.

Codecademy review

Now that I have also reviewed CodeAvengers, let's just not waste your time: If you're looking at HTML / CSS / JavaScript training, go there right away, and maybe come back to Codecademy afterwards.

In order for you to understand this review, let me simply remind that prior to trying Codecademy, I was an expert in PHP, and good enough in HTML/CSS/JS to write a web GUI framework that would destroy sencha and google's libs (disclaimer: I do have more important stuff to do)

I took two days to do all the language paths on Codecademy and a few API ones (somehow, most of the APIs are from services that I never heard about) to really understand the potential value of their approach (I love education and code).

About those paths:

• PHP : Don't do this. this path is utter trash. It's wrong in many ways, covers mostly nothing, and ends with basic OO crap instead of learning how to code
• HTML : It may be used for a first contact with HTML. It's very shallow (even much shallower than HTML itself) and is full of unrealistic and useless examples. 
• CSS : Basically it's a good start, but really incomplete.  Shallow as well, but it ain't half bad, focused on retarded design approaches though, nothing about responsive or how em,%, absolutes can be your friends
• JavaScript : A good first introduction as long as you know where they went wrong, otherwise it's potentially dangerous. this one is a bit better, very shallow as well, but since this is programming, they've added a bit of bad practice to it, in order to keep things fresh. 
• Python : A nice first introduction, long focus on irrelevant things (who the fuck drops half of the items from their array unless you want to go threading?) but nice anyway. Unfortunately, lots and lots of bad coding practice, bad examples, no user input handling, etc.
• Ruby : like Python, but better. Still some bad coding practice and no input handling, but the topics covered are a bit more relevant.
• APIs: this part is murder: there's the twitter API, that requires you to log in (that's bad), the Youtube API, that doesn't and is infinitely simple, and then a bunch of useless APIs that noone is ever going to use in their whole programming life, and literally NOTHING about the facebook or linkedin APIs, which are the most likely to be used.

This was fun, I learned a lot, and the process was somewhat efficient, even though probably not as much as me rushing for two days in one direction (although that would be specialization and not introduction, and I've had major successes in self-teaching without any platforms).

BUT

• way too much OO (I know the noskills are going to disagree, but OO is a philosophy and shouldn't be part of teaching code, surely not when teaching innocent noobs who couldn't possibly know better)

• no serious languages (C,lisp,Fortran,ASM,C++)

• it is obvious that most of the examples are written by people who code far worse than I do and don't have great teaching skills either

• the only refactoring topic actually brought a perfectly readable piece of code to ok-ish length, and then went in the one-liner territory for no reason. (if you do prefer code density, just use APL, at least it doesn't have an alternative long syntax)

• many courses have way too many steps, some of which are full of nothing, and there's no shortcut or hotkey to skip a useless step

• most of those steps have very bad unit tests that allow either wrong answers OR far worse, refuse much better answers

• most steps are really about hand-holding, and that's without checking the tips, which I'm sure do the rest of the work for you. That makes the progress much easier but really irrelevant, as nobody stores information they didn't have to search for (i.e. instead of talking about puts all the time, they should say it once, and make you remember it, telling you to "write" to the console, rather than print or puts or echo all the time)

• I almost forgot, but their js crashes, often, and you'll have to f5 that tab in order to get out of it. I even got a blue screen (i normally never do) using windows 7, chrome and Codecademy - WTF.

• Some of the obscure services API (especially gilt) have HORRIBLE horrible disgusting crappy tutorials, once more hitting the nail on the head about user-generated crap

• Let's face it, if I could do the whole thing in two days, it probably lacks depth and value

In conclusion

It seems Codecademy (and their API tutorial page shows this, with lots of unknown services APIs using that page as ad space) is waiting for user-generated content, but I can't see that working - users are (everyone is) mostly average, but ideally you'll want tutoring material to be written by the best shrinks based on the content provided by the best coders.

I agree that would be far above university standards, mostly because of the better psychology, but then that's a vision that's worth shooting for.

At their stage and with their funding, the low quality of the courses, both in terms of code quality and educational quality, it feels as if they invested everything in marketing, and that's just sad. I think it's time for them to upgrade their tutorials, and expand far beyond their limited scope and quality.

Right now, I would recommend Codecademy only for people who will never really have to code but have to have an idea of how it can work.

If you intend to be a programmer, you're far better off without any tutorial, just asking questions and questioning the answers while you achieve real-world goals.