HTML

These are the HTML-specific coding styles. Anything mentions here overrides/adds to the "In General" guides. The only 1 principle when coding HTML is that:

  • Be consistent. As long as it is sharing a single pattern, it is maintainable.

#1- For Any Link, State Protocol

  • State the full URL including the protocol (e.g. https).
  • Avoid using insecure protocol.
<!-- Recommended -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

<!-- Not recommended: omits the protocol -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>

<!-- Not recommended: uses HTTP -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>


Rationale

  • Security purposes.

#2 - Indentation

  • use 2 spaces tab. Not 8.


Rationale

  • The fact that some elements (especially <table>) requires a minimum 4 indentation levels in order to make itself complete. Hence, 8 spaces tab is not suitable.
  • Use tab as it is designed for indentation.

#3 - Naming Convention

  • Use lowercase at all cost (except for values like full name).
<!-- Recommended -->
<img src="google.png" alt="Google">

<!-- Not recommended -->
<A HREF="/">Home</A>


Rationale

  • Distinguish between tags, its descriptions and values.
  • Less complications.

#4 - Comments

  • Use minification and compression for post-processing HTML output.
  • Follow Generalized practice when you use minification compression for your HTML output.
  • Use sparingly otherwise.


Rationale

  • Minification process will strip the comments from the output HTML. Hence, it is safe to use comments.
  • Minify HTML reduces network payload size.

#5 - Use HTML5

  • Use HTML5 instead of other version.
  • Use tools like W3C Validator to validate site.
  • Use UTF-8 characters set.

Recommended:

<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

Not recommended:

<html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>


Rationale

  • Security and modern browsers interpretation.

#6 - Use HTML5 Semantics

  • Use the correct tag for the correct purpose.
  • DO NOT abuse <div> tag.

Recommended:

<!-- Recommended -->
<a href="recommendations/">All recommendations</a>

Not recommended:

<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>


Rationale

  • Built-in syntax checkup.
  • Purposeful checking and simpler codes.

#7 - Provide Alternate to Media Tags

  • Always provide the alt meta to your media tags like <img>.
  • Make sure the statement in the alt meta presents something as part of the design when the media failed to render.

Recommended:

<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

Not recommended:

<!-- Not recommended -->
<img src="spreadsheet.png">


Rationale

  • Media contents do fail when connectivity is bad or user explicitly blocks them. Hence, alternate text is used instead.

#8 - HTML is for Contents Only (Separation of Concerns)

  • Only present the contents and avoid using formatting tags like bold <b>, underline <u>, or center alignment <center>.
  • Leave formatting and design to only CSS.
  • Leave animations and triggers to only JavaScript (except CSS supported styling animations).
  • DO NOT mix them up.

Recommended:

<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
  doing it: separating concerns and avoiding anything in the HTML of
  my website that is presentational.
<p>It’s awesome!

Not recommended:

<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
  <u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
  my website without doing everything all over again!</center>


Rationale

  • Tools are designed for a clear reason. Use them according to their purpose. This makes web development simple to build and to maintain.

#9 - DO NOT use Entity References

  • HTML5 uses UTF-8. Use them.
  • Leave entity references back to the back-end server processing.

Recommended:

<!-- Recommended -->
The currency symbol for the Euro is “€”.

Not recommended:

<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.


Rationale

  • Maintainability.
  • Security reason.

#10 - Only Avoid Optional Tags When Necessary

  • Priority one is always about maintainability. Speed does not matter if the tags are wrong.
  • If the team and the HTML file is small, you may omit the optional tag based on the W3C rules.
  • DO NOT omit for large HTML files.
  • If in doubt or forgetful, DO NOT omit.


Not Omitting Version:

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

Omitting Version:

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


Rationale

  • By practicing omission, there are hidden rules to comply with. Omitting the tag without complying to the hidden rules can cause devastation over performance gain.
  • Considering new developers who are not experienced with HTML5 and of course hidden rules = poor maintainable codes.

#11 - Avoid type attributes for CSS and JavaScript

  • If the CSS tag is sourcing from a .css file, do not use it.
  • If the JavaScript is sourcing from a .js file, do not use it.

Recommended:

<link rel="stylesheet" href="https://www.google.com/css/maia.css">
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>

Not recommended:

<!-- Recommended -->
<link rel="stylesheet" href="https://www.google.com/css/maia.css" type="text/css">
<script src="https://www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>


Rationale

  • link and script tags are configured default to interpret CSS and JavaScript files respectively. Make use of them.
  • This is backward-compatible with old browsers.

#12 - One line for One Main Tag

  • Preserve every line for new block.
  • Only embed when the line is clean, comprehensible, and applicable.

Recommended:

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe</li>
  <li>Larry</li>
  <li>Curly</li>
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income</th>
      <th scope="col">Taxes</th>
  <tbody>
    <tr>
      <td>$ 5.00</td>
      <td>$ 4.50</td>
</table>


Rationale

  • link and script tags are configured default to interpret CSS and JavaScript files respectively. Make use of them.
  • This is backward-compatible with old browsers.

#13 - Break Long Lines

  • Break the meta descriptions using common sense.
  • Append an indent for the sub-elements after breaking.

Recommended:

<md-progress-circular
    md-mode="indeterminate"
    class="md-accent"
    ng-show="ctrl.loading"
    md-diameter="35">
</md-progress-circular>


<md-progress-circular md-mode="indeterminate"
                      class="md-accent"
                      ng-show="ctrl.loading"
                      md-diameter="35">
</md-progress-circular>


Rationale

  • Although this is HTML5, do not torture yourself with long line.
  • Make it friendly and single direction scrolling.

That's all for HTML coding style.