HTML代码规范
一般规则
一般样式规则
[Protocol]
尽可能使用HTTPS用于嵌入式资源。
除非图像不能通过HTTPS获得,否则对于图像和其他媒体文件,样式表和脚本应始终使用HTTPS。
<!--不推荐:省略协议-->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<!--不推荐:使用HTTP-->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
<!--推荐-->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
/* 不建议:省略协议 */
@import '//fonts.googleapis.com/css?family=Open+Sans';
/* 不推荐:使用HTTP */
@import 'http://fonts.googleapis.com/css?family=Open+Sans';
/* 推荐 */
@import 'https://fonts.googleapis.com/css?family=Open+Sans';
通用格式规则
[Indentation]
每次缩进2个空格。
请勿使用制表符或将制表符和空格混合使用缩进。
<ul>
<li>Fantastic
<li>Great
</ul>
.example {
color: blue;
}
[Capitalization]
仅使用小写字母。
所有代码都必须小写:这适用于HTML元素名称,属性,属性值(除非text/CDATA),CSS选择器,属性和属性值(字符串除外)。
<!--不推荐-->
<A HREF="/">Home</A>
<!--推荐-->
<img src="google.png" alt="Google">
/* 不推荐 */
color :#E5E5E5;
/* 推荐 */
color: #e5e5e5;
[Trailing Whitespace]
删除尾随空格。尾部的空格是不必要的。
<!--不推荐--> <p>What?_
<!--推荐--> <p>Yes please.
一般元规则
[Encoding]
使用UTF-8(no BOM)。
确保您的编辑器使用UTF-8作为字符编码,并且没有字节顺序标记。
通过指定HTML模板和文档中的编码。
[Comments]
尽可能解释代码。
使用注释来解释代码:它涵盖了什么,它的目的是什么,为什么使用或首选各自的解决方案?
[Action Items]
使用TODO来标记待办事项和动作项。
仅使用关键字TODO
突出显示待办事项,而不要使用其他常见格式(如@@
)。
在冒号后附加操作项,如TODO: action item。
{# TODO(john.doe): revisit centering #}
<center>Test</center>
<!-- TODO: remove optional tags --->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
HTML
HTML样式规则
[Document Type]
使用HTML5。
HTML5(HTML语法)是首选的所有HTML文档:<!DOCTYPE html>
。
(建议使用HTML,例如text/html。不要使用XHTML。XHTML,因为 application/xhtml+xml既缺乏浏览器也没有基础结构支持,并且优化空间更少。)
但不要关闭void元素,即,使用 <br>
,而不是 <br />
。
[HTML Validity]
尽可能使用有效的HTML。
使用有效的HTML代码,除非由于文件大小等其他原因HTML无法做到。
使用有效的HTML是可测试的基线质量属性,有助于了解技术要求和约束,并确保正确使用HTML。
<!--不推荐-->
<title>Test</title>
<article>This is only a test.
<!--推荐-->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
[Semantics]
根据目的使用HTML,使用语义化元素(标签)。例如,
出于可访问性,重用和代码效率的原因,HTML语义化至关重要。
<!--不推荐-->
<div onclick="goToRecommendations();">All recommendations</div>
<!--推荐-->
<a href="recommendations/">All recommendations</a>
[Multimedia Fallback]
提供多媒体的替代内容。
对于多媒体,如图像,视频,动画对象canvas,确保提供其他访问方式。
出于可访问性的原因,提供替代内容非常重要:对于图像,如果没有@alt
,盲人用户几乎无法理解图像的含义。
<!--不推荐-->
<img src="spreadsheet.png">
<!--推荐-->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
[Separation of Concerns]
结构与表示、行为分开。
严格分开结构(markup),表示形式(styling)和行为(scripting),并尽量将三个之间的交互保持最小。也就是说,确保文档和模板仅包含HTML和仅用于结构目的的HTML。将所有表示形式的内容移入样式表,并将所有行为形式的脚本移入脚本。
另外,通过从文档和模板中链接尽可能少的样式表和脚本,使交互范围尽可能小。
出于维护原因,将结构与表示与行为分开很重要。
<!--不推荐-->
<!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>
<!--推荐-->
<!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!
[Entity References]
不要使用实体引用。
如果文件和编辑器以及团队之间使用相同的编码(UTF-8),不需要使用诸如&``mdash;
、&``rdquo;
或&``#x263a;
之类的实体引用。
唯一的例外情况适用于在HTML中具有特殊含义的字符(如<
和&
)以及控制字符或“不可见”字符(如不间断空格)。
<!--不推荐-->
The currency symbol for the Euro is “&eur;”.
<!--推荐-->
The currency symbol for the Euro is “€”.
[Optional Tags]
省略可选标签(可选)。
出于文件大小优化和可扫描性的目的,可以考虑省略可选标签。在HTML5规范定义什么标签可以被省略。
<!--不推荐-->
<!DOCTYPE html>
<html>
<head>
<title>Spending money, spending bytes</title>
</head>
<body>
<p>Sic.</p>
</body>
</html>
<!--推荐-->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.
[type Attributes]
省略样式表和脚本的type
属性。
HTML5将text/css
和 text/javascript
作为默认值,写type属性是不必要的,即使旧的浏览器也可以安全地完成。
HTML格式规则
[General Formatting]
对每个块,列表或表元素使用换行符,并对每个此类子元素缩进。
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
<table>
<thead>
<tr>
<th scope="col">Income
<th scope="col">Taxes
<tbody>
<tr>
<td>$ 5.00
<td>$ 4.50
</table>
[HTML Line-Wrapping]
中断长行(可选)。
一行的长度过大影响可读性,换行的阈值取决于prettier的设定值。换行时,每条连续行应与原始行有缩进。
<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>
[HTML Quotation Marks]
引用属性值时,请使用双引号。
在属性值周围使用双引号(""
)而不是单引号(''
)。
<!--不推荐-->
<a class='maia-button maia-button-secondary'>Sign in</a>
<!--推荐-->
<a class="maia-button maia-button-secondary">Sign in</a>