HTML(5) 代碼規(guī)范

TML 代碼約定

很多 Web 開發(fā)人員對 HTML 的代碼規(guī)范知之甚少。

在2000年至2010年，許多Web開發(fā)人員從 HTML 轉(zhuǎn)換到 XHTML。

使用 XHTML 開發(fā)人員逐漸養(yǎng)成了比較好的 HTML 編寫規(guī)范。

而針對于 HTML5 ，我們應該形成比較好的代碼規(guī)范，以下提供了幾種規(guī)范的建議。

使用正確的文檔類型

文檔類型聲明位于HTML文檔的第一行：

<!DOCTYPE html>

如果你想跟其他標簽一樣使用小寫，可以使用以下代碼：

<!doctype html>

使用小寫元素名

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

推薦使用小寫字母：

混合了大小寫的風格是非常糟糕的。
開發(fā)人員通常使用小寫 (類似 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)會發(fā)生錯誤。

省略 <head>?

在標準 HTML5 中， <head>標簽是可以省略的。

默認情況下，瀏覽器會將 <body> 之前的內(nèi)容添加到一個默認的 <head> 元素上。

實例

<!DOCTYPE html>

<html>

<body>

<h1>這是一個標題</h1>

<p>這是一個段落。</p>

</body>

</html>

嘗試一下 ?

	現(xiàn)在省略 head 標簽還不推薦使用。

元數(shù)據(jù)

HTML5 中 <title> 元素是必須的，標題名描述了頁面的主題:

標題和語言可以讓搜索引擎很快了解你頁面的主題:

<!DOCTYPE html>

<head>

</head>

HTML 注釋

注釋可以寫在  中:

比較長的評論可以在  中分行寫：

<!--

這是一個較長評論。這是一個較長評論。這是一個較長評論。

這是一個較長評論這是一個較長評論。這是一個較長評論。

-->

長評論第一個字符縮進兩個空格，更易于閱讀。

樣式表

樣式表使用簡潔的語法格式 ( type 屬性不是必須的):

短的規(guī)則可以寫成一行:

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

長的規(guī)則可以寫成多行:

body {

background-color: lightgrey;

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

font-size: 16em;

color: black;

}

將左花括號與選擇器放在同一行。
左花括號與選擇器間添加以空格。
使用兩個空格來縮進。
冒號與屬性值之間添加已空格。
逗號和符號之后使用一個空格。
每個屬性與值結尾都要使用符號。
只有屬性值包含空格時才使用引號。
右花括號放在新的一行。
每行最多 80 個字符。

	在逗號和分號后添加空格是常用的一個規(guī)則。

在 HTML 中載入 JavaScript

使用簡潔的語法來載入外部的腳本文件 ( type 屬性不是必須的 ):

使用 JavaScript 訪問 HTML 元素

一個糟糕的 HTML 格式可能會導致 JavaScript 執(zhí)行錯誤。

以下兩個 JavaScript 語句會輸出不同結果:

實例

var obj = getElementById("Demo")

var obj = getElementById("demo")

HTML 中 JavaScript 盡量使用相同的命名規(guī)則。

訪問 JavaScript 代碼規(guī)范。

使用小寫文件名

大多 Web 服務器 (Apache, Unix) 對大小寫敏感： london.jpg 不能通過 London.jpg 訪問。

其他 Web 服務器 (Microsoft, IIS) 對大小寫不敏感： london.jpg 可以通過 London.jpg 或 london.jpg 訪問。

你必須保持統(tǒng)一的風格，我們建議統(tǒng)一使用小寫的文件名。

文件擴展名

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

CSS 文件后綴是 .css 。

JavaScript 文件后綴是 .js 。

.htm 和 .html 的區(qū)別

.htm 和 .html 的擴展名文件本質(zhì)上是沒有區(qū)別的。瀏覽器和 Web 服務器都會把它們當作 HTML 文件來處理。

區(qū)別在于：

.htm 應用在早期 DOS 系統(tǒng)，系統(tǒng)現(xiàn)在或者只能有三個字符。

在 Unix 系統(tǒng)中后綴沒有特別限制，一般用 .html。

技術上區(qū)別

如果一個 URL 沒有指定文件名 (如 http://www.runoob.com/css/), 服務器會返回默認的文件名。通常默認文件名為 index.html, index.htm, default.html, 和 default.htm。

如果服務器只配置了 "index.html" 作為默認文件，你必須將文件命名為 "index.html", 而不是 "index.htm"。

但是，通常服務器可以設置多個默認文件，你可以根據(jù)需要設置默認文件嗎。

不管怎樣，HTML 完整的后綴是 ".html"。

如您還有不明白的可以在下面與我留言或是與我探討QQ群308855039，我們一起飛！

obert C. Martin寫的《Clean Code》是我讀過的最好的編程書籍之一，若沒有讀過，推薦你將它加入書單。

注釋就意味著代碼無法自說明 —— Robert C. Martin

Martin在文中詳細討論了代碼注釋，我不會完全重復他的話。簡而言之，他的意思就是，這些注釋是注定會過時的。程序執(zhí)行時會忽視注釋，所以無法保證這些說明注釋會準確的描述代碼作用。所以最好的方式是讓代碼自說明，如此，按照代碼邏輯，程序員和程序獲取到的信息是一致的。

思考如下代碼：

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

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

if (employee.isEligibleForFullBenefits()) { …}

代碼需要“言行一致”，注釋是能夠被命名良好的函數(shù)或變量取代的。Martin的意思并不是說永不使用注釋，而是應該盡量避免寫注釋，注釋就意味著代碼無法自說明。

那么對CSS而言呢？

我非常贊同Martin關于注釋的看法。當涉及到聲明式的語言如CSS時，就發(fā)現(xiàn)了一些有趣的地方。聲明式語言式必須符合對應格式的，而CSS選擇器基本是由HTML結構決定的。對這種代碼結構，我們能做的不多，這是否意味著CSS代碼必須注釋滿天飛？

額，也許吧。有很多的理由使用注釋，且注釋的寫法也有很多。讓我們來看一些注釋，思考這些注釋是否應該添加。先從答案顯然的開始吧，然后一步步深入到不那么好判斷的。

不好：多此一舉的注釋

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

// Addressesaddress {…}

顯然，address是關于地址的選擇器

// Unordered and Ordered listsul,ol {…}

還有？

// Blockquotesblockquote {…}

趕緊停！

千萬不要寫那種注釋，趕緊刪掉這些多余的東西，它僅僅是在重復代碼而已。當然，新版本的Bootstrap已經(jīng)刪除掉大部分多此一舉的無用注釋了。

不好：塊分隔注釋

對CSS而言，塊分隔注釋是非常特殊的，如下：

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

這種注釋能把我逼瘋。我能想到為什么會寫下這種注釋：有時候我們的CSS會寫得非常長，當在超過千行的文件內(nèi)查找時，就需要這種帶特殊標志的注釋來幫助快速搜索。

但事實上，很長很長的CSS文件已經(jīng)不再流行了。若你的項目確實需要這種很大的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;

這條注釋很有意思，看起來似乎并不違反“說明原因而不是說明作用？”規(guī)則，它表明由于可能會被一些意料之外的繼承字體屬性影響，所以用導入的方式來重置字體屬性。

但進一步來看，顯然在文件頭導入重置樣式的唯一的解釋就是擔心被繼承樣式影響。

所以，我認為這種注釋也是不需要的，因為導入函數(shù)名字已經(jīng)說明用途了，盡量讓函數(shù)名切合作用，如reset-inherited-font或類似的名字，不僅清晰說明了用途還是說明了原因。這個是一個函數(shù)調(diào)用，函數(shù)名已經(jīng)足夠解釋了。優(yōu)先用這種方式來說明用途可以替代一些注釋。

CSS預處理器讓CSS更接近傳統(tǒng)編程語言。盡可能使用命名良好且有意義的變量和函數(shù)，這樣能讓代碼更清晰。

不好: 過時的注釋

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

“as with > li > a”是什么意思？我第一反應就是也許在文件中還有一個> li > a的選擇器，而這行代碼就是指那個選擇器。也許文件中有一段注釋會專門解釋為何這樣寫，但我將文件重頭到尾都看了一邊，發(fā)現(xiàn)并沒有這個選擇器。文件只有一個.dropdown-item選擇器下有一個nowrap屬性，也許是就是指這個？或者也許這段注釋是指某行已經(jīng)被刪除的代碼或引入其他文件中的代碼？若想要徹底弄清楚這個注釋的作用，唯一的方法就是翻遍整個git記錄了吧。

這是一個過時的注釋，也許它以前是有用的，但卻長時間沒有用到，所以過時了。這也許就是為什么Robert Martin對注釋的看法：若注釋對應的代碼更新了注釋就沒用了，甚至更糟糕，注釋可能會將你引到錯誤的方向。若發(fā)現(xiàn)這樣的注釋，一定要刪掉。它完全沒用，而且會浪費時間去思考到底有啥用？

有時有用的：有特殊意義的注釋

如下是一段帶注釋的代碼：

.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混入模式。重構為一個函數(shù)，該函數(shù)能在其他地方定義，并且讓代碼更清晰。考慮如下代碼：

.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;
}

這段代碼沒有用任何注釋，但其功用很清晰，因為它使用的公用函數(shù)在其他模塊也能用到。我將width:100%保留下來而不是移到函數(shù)中，因為若將函數(shù)混和代碼時，width:100%可能會引起一些其他問題。

在我開始發(fā)現(xiàn)“代碼異味（Code Smell）”之前，一開始.dropdown-item代碼有十行，我非常喜歡用mixin，mixin是一個能極大減少代碼行數(shù)的好東西，它能讓我們快速的知道代碼的大致用途。

雖然使用函數(shù)重構代碼并不是都這樣有效，但盡量多用。

好：注解難懂的補丁性的代碼

我對注釋也不是總那么苛刻的，比如我就很難找到下面的注釋的問題，若你曾看過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庫的目標是提供一個完全一致樣式環(huán)境，所以需要很多這樣的注釋。選擇器都是類型和屬性選擇器，沒有任何class名，同時由于不是可命名的class名，所以自文檔非常困難。

如下為另一段Bootstrap的注釋：

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

一個Github鏈接，非常有用。即使不打開連接也能知道這兒是一個bug，而且有可能是一個非常難定位的bug。若有需要，可以通過鏈接獲取更多信息。最棒的是，因為沒有大段大段的文本去解釋bug，所以它并不會打亂代碼邏輯，同時也告訴我們哪里可以獲取更多信息。若使用項目與事務跟蹤工具如JIRA，那么可以直接在注釋中與編號關聯(lián)起來。

當然，不是每個打補丁的代碼都要這樣注釋，但若bug不是那么容易發(fā)現(xiàn)，而且與瀏覽器怪癖有關，那么還是這樣注釋吧。

好：指令式注釋

一些工具如KSS , 會在CSS文件中創(chuàng)建一些樣式規(guī)范。如下：

/*
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
*/

這不僅僅是注釋，這是規(guī)范，它能被KSS解析并用于生成HTML。這已經(jīng)算是項目文檔的一部分了，而且不得不說，這比手動創(chuàng)建一個分離的HTML文件要好很多，因為其在同一個文件內(nèi)且始終與代碼相匹配。

另外一種指令式注釋為許可信息，當使用第三方庫并在注釋中注明許可信息時，一般都需要包含。

而我貼出Robert Martin關于注釋的話時，似乎應該解釋一下，但我沒有那么做。因為我認為這是一句容易理解的話，若你還在代碼中到處寫注釋，那么請先思考是否合理。

英文：Keith J. Grant 譯文：眾成翻譯/KING

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

本文摘自互聯(lián)網(wǎng)，如有侵權，請與小編聯(lián)系進行刪除

Java編程中，注釋是一種重要的語法元素，允許開發(fā)者在代碼中添加描述性信息，而不會影響代碼的執(zhí)行。注釋對于理解代碼的邏輯、功能以及維護代碼都起著至關重要的作用。Java支持三種類型的注釋，分別是單行注釋、多行注釋和文檔注釋。

單行注釋

單行注釋用于解釋或描述代碼中的某一行或某一部分。以雙斜杠（//）開頭，直到該行結束。Java編譯器會忽略單行注釋及其后面的所有內(nèi)容。

例如：

// 這是一個單行注釋
int a = 5; // 聲明一個整數(shù)變量a并賦值為5

在上面的代碼中，第一行是一個單獨的單行注釋，而第二行中的注釋則緊跟在代碼后面，用于解釋該行代碼的作用。

多行注釋

多行注釋用于解釋或描述代碼中的多行內(nèi)容。它以（/*）開頭，以（*/）結束。Java編譯器會忽略這兩個符號之間的所有內(nèi)容。

例如：

/*
這是一個多行注釋，
可以跨越多行來解釋或描述代碼的功能和邏輯。
*/
int b = 10;
int c = b * 2;

在上面的代碼中，多行注釋用于解釋接下來的兩行代碼的作用。

文檔注釋

文檔注釋是一種特殊的多行注釋，它以“/**”開頭，以“*/”結束。主要用于生成API文檔，幫助開發(fā)者了解和使用類或方法。JavaDoc工具可以從源代碼中提取文檔注釋，并生成HTML格式的API文檔。

文檔注釋中可以包含一些特殊的標簽，如@author（作者）、@version（版本）、@param（參數(shù)說明）、@return（返回值說明）、@throws（拋出異常說明）等。

例如：

/**
 * 這是一個文檔注釋的示例
 *
 * @author 張三
 * @version 1.0
 */
public class MyClass {

    /**
     * 計算兩個數(shù)的和
     *
     * @param a 第一個加數(shù)
     * @param b 第二個加數(shù)
     * @return 兩個數(shù)的和
     */
    public int sum(int a, int b) {
        return a + b;
    }
}

在上面的代碼中，我們使用了文檔注釋來描述類和方法的功能、作者和版本等信息。這些信息可以通過JavaDoc工具提取并生成API文檔。

總結

注釋是Java編程中不可或缺的一部分，能夠幫助我們更好地理解代碼，提高代碼的可讀性和可維護性。掌握并合理使用注釋，是成為一名優(yōu)秀Java開發(fā)者的必備技能之一。

在線咨詢

上一篇：C# WPF實用的注冊窗體
下一篇：這款免費在線PDF工具，我愿稱其為最強

您的項目需求

*請認真填寫需求信息，我們會在24小時內(nèi)與您取得聯(lián)系。

整合營銷服務商

HTML(5) 代碼規(guī)范

單行注釋

多行注釋

文檔注釋

總結

您的項目需求