search

google / styleguide

Style guides for Google-originated open-source projects
https://google.github.io/styleguide/
Apache License 2.0
37.45k stars 13.3k forks source link

Follow the google HTML style guide in the style guide's HTML #363

Open greggman opened 6 years ago

greggman commented 6 years ago

The style guide's HTML file does not itself follow it's own rules

From the guide

Omit optional tags (optional).

For file size optimization and scannability purposes, consider omitting optional tags. The HTML5 specification defines what tags can be omitted.

(This approach may require a grace period to be established as a wider guideline as it’s significantly different from what web developers are typically taught. For consistency and simplicity reasons it’s best served omitting all optional tags, not just a selection.)

   <!-- Not recommended -->
   <!DOCTYPE html>
   <html>
     <head>
       <title>Spending money, spending bytes</title>
     </head>
     <body>
       <p>Sic.</p>
    </body>
   </html>

   <!-- Recommended -->
   <!DOCTYPE html>
   <title>Saving money, saving bytes</title>
   <p>Qed.

then compare to the style guide's own HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Google HTML/CSS Style Guide</title>
<link rel="stylesheet" href="javaguide.css">
<script src="include/styleguide.js"></script>
<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
<script src="include/jsguide.js"></script>
</head>
<body onload="initStyleGuide();">
<div id="content">
<h1>Google HTML/CSS Style Guide</h1>
<h2 id="Background">1 Background</h2>

<p>This ...</p>
...

It seems like according to the guide it should be

<!DOCTYPE html>
<meta charset="utf-8">
<title>Google HTML/CSS Style Guide</title>
<link rel="stylesheet" href="javaguide.css">
<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
<div id="content">
<h1>Google HTML/CSS Style Guide</h1>
<h2 id="Background">1 Background</h2>

<p>This ...
...

<script src="include/styleguide.js"></script>
<script src="include/jsguide.js"></script>

and the script should be either moved to the end or tagged with defer so no need for <body onload="noreasonforthis">

tonyruscoe commented 6 years ago

Hi Greggman. Apologies for the delay in responding to this!

I agree that all of our HTML-formatted style guides should ideally follow the recommendations provided by our HTML/CSS Style Guide. We have a process for converting our internal style guides into these external ones, so there’s little point updating the HTML files in this repo directly.

I’ll file an internal issue for improving these templates. Thanks for the feedback!

tonyruscoe commented 6 years ago

I should probably add that the HTML/CSS Style Guide recommendation to omit optional tags is an optional recommendation, but I think there are other ways in which our style guide markup doesn’t follow our style guide.

vapier commented 4 months ago

i think the big problem with most of our HTML files is that they're generated, so i don't know that styleguide matters as much with those