HTML(5) 代码规范

TML 代码约定

很多 Web 开发人员对 HTML 的代码规范知之甚少。

在2000年至2010年，许多Web开发人员从 HTML 转换到 XHTML。

使用 XHTML 开发人员逐渐养成了比较好的 HTML 编写规范。

而针对于 HTML5 ，我们应该形成比较好的代码规范，以下提供了几种规范的建议。

使用正确的文档类型

文档类型声明位于HTML文档的第一行：

<!DOCTYPE html>

如果你想跟其他标签一样使用小写，可以使用以下代码：

<!doctype html>

使用小写元素名

HTML5 元素名可以使用大写和小写字母。

推荐使用小写字母：

混合了大小写的风格是非常糟糕的。
开发人员通常使用小写 (类似 XHTML)。
小写风格看起来更加清爽。
小写字母容易编写。

不推荐:

<p>这是一个段落。</p>

</SECTION>

非常糟糕:

<p>这是一个段落。</p>

</SECTION>

推荐:

<body>

<p>菜鸟教程，学的不仅是技术，更是梦想。

菜鸟教程，学的不仅是技术，更是梦想。

菜鸟教程，学的不仅是技术，更是梦想。</p>

</body>

表格实例:

<table>

<tr>

<th>Description</th>

</tr>

<tr>

<td>Description of A</td>

</tr>

<tr>

<td>Description of B</td>

</tr>

</table>

列表实例:

<ol>

<li>London</li>

<li>Paris</li>

<li>Tokyo</li>

</ol>

省略 <html> 和 <body>?

在标准 HTML5 中， <html> 和 <body> 标签是可以省略的。

以下 HTML5 文档是正确的:

实例:

<!DOCTYPE html>

<head>

</head>

<h1>这是一个标题</h1>

<p>这是一个段落。</p>

尝试一下 »

不推荐省略 <html> 和 <body> 标签。

<html> 元素是文档的根元素，用于描述页面的语言：

<!DOCTYPE html>

声明语言是为了方便屏幕阅读器及搜索引擎。

省略 <html> 或 <body> 在 DOM 和 XML 软件中会崩溃。

省略 <body> 在旧版浏览器 (IE9)会发生错误。

省略 <head>?

在标准 HTML5 中， <head>标签是可以省略的。

默认情况下，浏览器会将 <body> 之前的内容添加到一个默认的 <head> 元素上。

实例

<!DOCTYPE html>

<html>

<body>

<h1>这是一个标题</h1>

<p>这是一个段落。</p>

</body>

</html>

尝试一下 »

	现在省略 head 标签还不推荐使用。

元数据

HTML5 中 <title> 元素是必须的，标题名描述了页面的主题:

标题和语言可以让搜索引擎很快了解你页面的主题:

<!DOCTYPE html>

<head>

</head>

HTML 注释

注释可以写在  中:

比较长的评论可以在  中分行写：

<!--

这是一个较长评论。这是一个较长评论。这是一个较长评论。

这是一个较长评论这是一个较长评论。这是一个较长评论。

-->

长评论第一个字符缩进两个空格，更易于阅读。

样式表

样式表使用简洁的语法格式 ( type 属性不是必须的):

短的规则可以写成一行:

p.into {font-family: Verdana; font-size: 16em;}

长的规则可以写成多行:

body {

background-color: lightgrey;

font-family: "Arial Black", Helvetica, sans-serif;

font-size: 16em;

color: black;

}

将左花括号与选择器放在同一行。
左花括号与选择器间添加以空格。
使用两个空格来缩进。
冒号与属性值之间添加已空格。
逗号和符号之后使用一个空格。
每个属性与值结尾都要使用符号。
只有属性值包含空格时才使用引号。
右花括号放在新的一行。
每行最多 80 个字符。

	在逗号和分号后添加空格是常用的一个规则。

在 HTML 中载入 JavaScript

使用简洁的语法来载入外部的脚本文件 ( type 属性不是必须的 ):

使用 JavaScript 访问 HTML 元素

一个糟糕的 HTML 格式可能会导致 JavaScript 执行错误。

以下两个 JavaScript 语句会输出不同结果:

实例

var obj = getElementById("Demo")

var obj = getElementById("demo")

HTML 中 JavaScript 尽量使用相同的命名规则。

访问 JavaScript 代码规范。

使用小写文件名

大多 Web 服务器 (Apache, Unix) 对大小写敏感： london.jpg 不能通过 London.jpg 访问。

其他 Web 服务器 (Microsoft, IIS) 对大小写不敏感： london.jpg 可以通过 London.jpg 或 london.jpg 访问。

你必须保持统一的风格，我们建议统一使用小写的文件名。

文件扩展名

HTML 文件后缀可以是 .html (或r .htm)。

CSS 文件后缀是 .css 。

JavaScript 文件后缀是 .js 。

.htm 和 .html 的区别

.htm 和 .html 的扩展名文件本质上是没有区别的。浏览器和 Web 服务器都会把它们当作 HTML 文件来处理。

区别在于：

.htm 应用在早期 DOS 系统，系统现在或者只能有三个字符。

在 Unix 系统中后缀没有特别限制，一般用 .html。

技术上区别

如果一个 URL 没有指定文件名 (如 http://www.runoob.com/css/), 服务器会返回默认的文件名。通常默认文件名为 index.html, index.htm, default.html, 和 default.htm。

如果服务器只配置了 "index.html" 作为默认文件，你必须将文件命名为 "index.html", 而不是 "index.htm"。

但是，通常服务器可以设置多个默认文件，你可以根据需要设置默认文件吗。

不管怎样，HTML 完整的后缀是 ".html"。

如您还有不明白的可以在下面与我留言或是与我探讨QQ群308855039，我们一起飞！

obert C. Martin写的《Clean Code》是我读过的最好的编程书籍之一，若没有读过，推荐你将它加入书单。

注释就意味着代码无法自说明 —— Robert C. Martin

Martin在文中详细讨论了代码注释，我不会完全重复他的话。简而言之，他的意思就是，这些注释是注定会过时的。程序执行时会忽视注释，所以无法保证这些说明注释会准确的描述代码作用。所以最好的方式是让代码自说明，如此，按照代码逻辑，程序员和程序获取到的信息是一致的。

思考如下代码：

// Check to see if the employee is eligible for full benefits// 检查员工是否有资格获取全部福利if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { …}

注释有用么？当然有用，但下面的方式可能更好：

if (employee.isEligibleForFullBenefits()) { …}

代码需要“言行一致”，注释是能够被命名良好的函数或变量取代的。Martin的意思并不是说永不使用注释，而是应该尽量避免写注释，注释就意味着代码无法自说明。

那么对CSS而言呢？

我非常赞同Martin关于注释的看法。当涉及到声明式的语言如CSS时，就发现了一些有趣的地方。声明式语言式必须符合对应格式的，而CSS选择器基本是由HTML结构决定的。对这种代码结构，我们能做的不多，这是否意味着CSS代码必须注释满天飞？

额，也许吧。有很多的理由使用注释，且注释的写法也有很多。让我们来看一些注释，思考这些注释是否应该添加。先从答案显然的开始吧，然后一步步深入到不那么好判断的。

不好：多此一举的注释

任何语言，多此一举的注释都是多余的，如下的示例出自Bootstrap3的早期版本：

// Addressesaddress {…}

显然，address是关于地址的选择器

// Unordered and Ordered listsul,ol {…}

还有？

// Blockquotesblockquote {…}

赶紧停！

千万不要写那种注释，赶紧删掉这些多余的东西，它仅仅是在重复代码而已。当然，新版本的Bootstrap已经删除掉大部分多此一举的无用注释了。

不好：块分隔注释

对CSS而言，块分隔注释是非常特殊的，如下：

/* ----------------- * TOOLTIPS * ----------------- */

这种注释能把我逼疯。我能想到为什么会写下这种注释：有时候我们的CSS会写得非常长，当在超过千行的文件内查找时，就需要这种带特殊标志的注释来帮助快速搜索。

但事实上，很长很长的CSS文件已经不再流行了。若你的项目确实需要这种很大的CSS文件，它应该是由多个小的部分，通过CSS预处理工具组合而成的。

不好：解释语法

又要用Bootstrap举例了，以下代码出自 _tooltips.scss:

// Allow breaking very long words so they don't overflow the tooltip's bounds// 设置长单词换行word-wrap: break-word;

这种方式和“多此一举的注释”类似，注释解释word-wrap属性的作用。这里有一篇文章讲到这种注释为什么不需要的原因，注释应该解释“为什么”，而不是“是什么”，即说明原因而不是说明作用（Why, not what）。

此处有一个例外，由于CSS有很多属性，也许有些属性是你完全不知道的，那么你用这种注释是正常的。

不好：对库进行介绍

如下是Bootstrap tooltips.scss文件的另一段注释：

// Our parent element can be arbitrary since tooltips are by default inserted as a// sibling of their target element. So reset our font and text properties to avoid// inheriting weird values.// 由于提示框会被默认插入到目标元素后作为一个兄弟元素，// 所以需要重置提示框的字体属性避免从父元素继承样式影响。@include reset-text();font-size: $font-size-sm;

这条注释很有意思，看起来似乎并不违反“说明原因而不是说明作用？”规则，它表明由于可能会被一些意料之外的继承字体属性影响，所以用导入的方式来重置字体属性。

但进一步来看，显然在文件头导入重置样式的唯一的解释就是担心被继承样式影响。

所以，我认为这种注释也是不需要的，因为导入函数名字已经说明用途了，尽量让函数名切合作用，如reset-inherited-font或类似的名字，不仅清晰说明了用途还是说明了原因。这个是一个函数调用，函数名已经足够解释了。优先用这种方式来说明用途可以替代一些注释。

CSS预处理器让CSS更接近传统编程语言。尽可能使用命名良好且有意义的变量和函数，这样能让代码更清晰。

不好: 过时的注释

.dropdown-header { … white-space: nowrap; // as with > li > a}

“as with > li > a”是什么意思？我第一反应就是也许在文件中还有一个> li > a的选择器，而这行代码就是指那个选择器。也许文件中有一段注释会专门解释为何这样写，但我将文件重头到尾都看了一边，发现并没有这个选择器。文件只有一个.dropdown-item选择器下有一个nowrap属性，也许是就是指这个？或者也许这段注释是指某行已经被删除的代码或引入其他文件中的代码？若想要彻底弄清楚这个注释的作用，唯一的方法就是翻遍整个git记录了吧。

这是一个过时的注释，也许它以前是有用的，但却长时间没有用到，所以过时了。这也许就是为什么Robert Martin对注释的看法：若注释对应的代码更新了注释就没用了，甚至更糟糕，注释可能会将你引到错误的方向。若发现这样的注释，一定要删掉。它完全没用，而且会浪费时间去思考到底有啥用？

有时有用的：有特殊意义的注释

如下是一段带注释的代码：

.dropdown-item { display: block; width: 100%; // For `<button>`s padding: $dropdown-item-padding-y $dropdown-item-padding-x; clear: both; font-weight: $font-weight-normal; color: $dropdown-link-color; text-align: inherit; // For `<button>`s white-space: nowrap; background: none; // For `<button>`s border: 0; // For `<button>`s}

这样的注释就是有用的，它们能告诉我们，这些特定的属性是为覆盖<button>样式而写的。这样的注释就是有用的，因为有时候代码的意图不是那么显而易见的。

但此时也需要问一个问题：有什么办法能让代码自说明呢？需要可以考虑将这些特定的属性移到第二个选择器中，专门为这些按钮设置的选择器。

.dropdown-item {
 display: block;
 padding: $dropdown-item-padding-y $dropdown-item-padding-x;
 clear: both;
 font-weight: $font-weight-normal;
 color: $dropdown-link-color;
 white-space: nowrap;
}
button.dropdown-item {
 width: 100%;
 text-align: inherit;
 background: none;
 border: 0;
}

这样就非常清晰且易于理解，但副作用就是：专门增加了一个特殊的选择器。

而相反，我认为这种方式非常利于使用mixin混入模式。重构为一个函数，该函数能在其他地方定义，并且让代码更清晰。考虑如下代码：

.dropdown-item {
 @include remove-button-styles;
 display: block;
 width: 100%;
 padding: $dropdown-item-padding-y $dropdown-item-padding-x;
 clear: both;
 font-weight: $font-weight-normal;
 color: $dropdown-link-color;
 white-space: nowrap;
}

这段代码没有用任何注释，但其功用很清晰，因为它使用的公用函数在其他模块也能用到。我将width:100%保留下来而不是移到函数中，因为若将函数混和代码时，width:100%可能会引起一些其他问题。

在我开始发现“代码异味（Code Smell）”之前，一开始.dropdown-item代码有十行，我非常喜欢用mixin，mixin是一个能极大减少代码行数的好东西，它能让我们快速的知道代码的大致用途。

虽然使用函数重构代码并不是都这样有效，但尽量多用。

好：注解难懂的补丁性的代码

我对注释也不是总那么苛刻的，比如我就很难找到下面的注释的问题，若你曾看过normalize.css的源码，你一定会注意到它满满的注释，不得不说，真是“极好的”注释。

欣赏一番：

/** * 1\. Add the correct box sizing in Firefox. * FF下正常的盒子模型 * 2\. Show the overflow in Edge and IE. * 在Edge和IE下overflow为visble */hr { box-sizing: content-box; /* 1 */ height: 0; /* 1 */ overflow: visible; /* 2 */}

若没有这些注释，你永远不知道为何这样写。修复特定浏览器bug的代码往往是晦涩难懂的，常常会被当做无用代码删掉。

由于Normalize库的目标是提供一个完全一致样式环境，所以需要很多这样的注释。选择器都是类型和属性选择器，没有任何class名，同时由于不是可命名的class名，所以自文档非常困难。

如下为另一段Bootstrap的注释：

/* Chrome (OSX) fix for https://github.com/twbs/bootstrap/issues/11245 */select { background: #fff !important;}

一个Github链接，非常有用。即使不打开连接也能知道这儿是一个bug，而且有可能是一个非常难定位的bug。若有需要，可以通过链接获取更多信息。最棒的是，因为没有大段大段的文本去解释bug，所以它并不会打乱代码逻辑，同时也告诉我们哪里可以获取更多信息。若使用项目与事务跟踪工具如JIRA，那么可以直接在注释中与编号关联起来。

当然，不是每个打补丁的代码都要这样注释，但若bug不是那么容易发现，而且与浏览器怪癖有关，那么还是这样注释吧。

好：指令式注释

一些工具如KSS , 会在CSS文件中创建一些样式规范。如下：

/*
Alerts
An alert box requires a contextual class to specify its importance.
一个警告信息框需要与语境有关的的类来指定其重要性
Markup:
<div>
 Take note of this important alert message.
</div>
alert-success - Something good or successful 好的或成功的
alert-info - Something worth noting, but not super important 不那么重要的
alert-warning - Something to note, may require attention 需要被提示并记录，需要引起注意的
alert-danger - Something important. Usually signifies an error. 非常重要的，常用于错误
Styleguide Alerts
*/

这不仅仅是注释，这是规范，它能被KSS解析并用于生成HTML。这已经算是项目文档的一部分了，而且不得不说，这比手动创建一个分离的HTML文件要好很多，因为其在同一个文件内且始终与代码相匹配。

另外一种指令式注释为许可信息，当使用第三方库并在注释中注明许可信息时，一般都需要包含。

而我贴出Robert Martin关于注释的话时，似乎应该解释一下，但我没有那么做。因为我认为这是一句容易理解的话，若你还在代码中到处写注释，那么请先思考是否合理。

英文：Keith J. Grant 译文：众成翻译/KING

zcfy.cc/article/thoughts-on-self-documenting-css

本文摘自互联网，如有侵权，请与小编联系进行删除

Java编程中，注释是一种重要的语法元素，允许开发者在代码中添加描述性信息，而不会影响代码的执行。注释对于理解代码的逻辑、功能以及维护代码都起着至关重要的作用。Java支持三种类型的注释，分别是单行注释、多行注释和文档注释。

单行注释

单行注释用于解释或描述代码中的某一行或某一部分。以双斜杠（//）开头，直到该行结束。Java编译器会忽略单行注释及其后面的所有内容。

例如：

// 这是一个单行注释
int a = 5; // 声明一个整数变量a并赋值为5

在上面的代码中，第一行是一个单独的单行注释，而第二行中的注释则紧跟在代码后面，用于解释该行代码的作用。

多行注释

多行注释用于解释或描述代码中的多行内容。它以（/*）开头，以（*/）结束。Java编译器会忽略这两个符号之间的所有内容。

例如：

/*
这是一个多行注释，
可以跨越多行来解释或描述代码的功能和逻辑。
*/
int b = 10;
int c = b * 2;

在上面的代码中，多行注释用于解释接下来的两行代码的作用。

文档注释

文档注释是一种特殊的多行注释，它以“/**”开头，以“*/”结束。主要用于生成API文档，帮助开发者了解和使用类或方法。JavaDoc工具可以从源代码中提取文档注释，并生成HTML格式的API文档。

文档注释中可以包含一些特殊的标签，如@author（作者）、@version（版本）、@param（参数说明）、@return（返回值说明）、@throws（抛出异常说明）等。

例如：

/**
 * 这是一个文档注释的示例
 *
 * @author 张三
 * @version 1.0
 */
public class MyClass {

    /**
     * 计算两个数的和
     *
     * @param a 第一个加数
     * @param b 第二个加数
     * @return 两个数的和
     */
    public int sum(int a, int b) {
        return a + b;
    }
}

在上面的代码中，我们使用了文档注释来描述类和方法的功能、作者和版本等信息。这些信息可以通过JavaDoc工具提取并生成API文档。

总结

注释是Java编程中不可或缺的一部分，能够帮助我们更好地理解代码，提高代码的可读性和可维护性。掌握并合理使用注释，是成为一名优秀Java开发者的必备技能之一。

在线咨询

上一篇：C# WPF实用的注册窗体
下一篇：这款免费在线PDF工具，我愿称其为最强

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

整合营销服务商

HTML(5) 代码规范

单行注释

多行注释

文档注释

总结

您的项目需求