作者 |

譯者| 王強(qiáng)

規(guī)劃| 小智

在移動(dòng)、Web 和桌面應(yīng)用程序或庫(kù)開(kāi)發(fā)領(lǐng)域，文檔對(duì)于應(yīng)用程序的成功起著非常重要的作用。 但如果您曾經(jīng)編寫(xiě)過(guò)文檔，您就會(huì)同意我的觀點(diǎn)：編寫(xiě)文檔是開(kāi)發(fā)人員最不喜歡做的事情之一。

與編寫(xiě)代碼（這是開(kāi)發(fā)人員的工作）不同，文檔必須易于每個(gè)人理解（這里的每個(gè)人不僅指開(kāi)發(fā)人員，還包括沒(méi)有技術(shù)背景的普通人）。 從技術(shù)上來(lái)說(shuō)，我們要把機(jī)器語(yǔ)言（代碼）翻譯成普通人能理解的語(yǔ)言，這說(shuō)起來(lái)容易做起來(lái)難。

雖然編寫(xiě)文檔可能會(huì)給您帶來(lái)沉重的負(fù)擔(dān)，但它是重要的一步sublime text 3 js代碼格式化，可以給您的用戶、您的同事，尤其是您自己帶來(lái)很多好處。

好的文檔可以幫助用戶

顯然，文檔可以幫助讀者理解代碼的工作原理。 但很多開(kāi)發(fā)人員有一個(gè)錯(cuò)誤的認(rèn)識(shí)，那就是他們認(rèn)為軟件的用戶就是編程專家。 在這種假設(shè)下，他們寫(xiě)的文檔可能只是幾頁(yè)薄頁(yè)，跳過(guò)了文檔應(yīng)包含的許多要點(diǎn)。 如果你精通編程語(yǔ)言，你可以自己找到問(wèn)題的解決方案。 如果你不是那么專業(yè)，在閱讀文檔時(shí)很容易迷失方向。

用戶文檔通常包括使用實(shí)踐或“操作方法”內(nèi)容。 為一般用戶創(chuàng)建文檔時(shí)，經(jīng)驗(yàn)法則是文檔應(yīng)該清晰直觀。 使用普通人容易理解的詞匯比使用專業(yè)術(shù)語(yǔ)或?qū)I(yè)習(xí)語(yǔ)更合適。 軟件的實(shí)際應(yīng)用實(shí)例也很受用戶歡迎。

良好的文檔布局設(shè)計(jì)還可以真正幫助用戶輕松瀏覽文檔的各個(gè)部分。 一些很好的例子包括文檔和“第一步”文檔，它們也是我最喜歡的榜樣。

良好的文檔可以幫助其他開(kāi)發(fā)人員

每個(gè)開(kāi)發(fā)人員都有自己的編碼風(fēng)格。 但在團(tuán)隊(duì)合作中，我們經(jīng)常需要與其他同事共享代碼。 因此，有必要讓大家達(dá)成共識(shí)，形成一套標(biāo)準(zhǔn)，讓大家步調(diào)一致。 寫(xiě)得好的文檔將成為團(tuán)隊(duì)必要的參考。

但與最終用戶文檔不同的是，此類文檔通常描述技術(shù)流程，例如代碼命名約定、展示開(kāi)發(fā)人員應(yīng)如何構(gòu)建特定頁(yè)面、API 如何工作以及一些代碼示例。 通常，我們還必須在代碼中編寫(xiě)文檔（稱為注釋）來(lái)描述注釋代碼的作用。

此外，如果將來(lái)有新成員加入團(tuán)隊(duì)，這種類型的文檔可以成為培訓(xùn)他們的一種節(jié)省時(shí)間且有效的方法，因此您不必一對(duì)一地向新人傳授代碼。

好的文檔也可以幫助開(kāi)發(fā)者自己

編程的有趣之處在于，有時(shí)甚至開(kāi)發(fā)人員自己也無(wú)法理解他們編寫(xiě)的代碼。 尤其是當(dāng)開(kāi)發(fā)人員幾個(gè)月甚至幾年沒(méi)有碰過(guò)自己寫(xiě)的代碼時(shí)，突然回來(lái)看自己的作品時(shí)，會(huì)感覺(jué)很奇怪。

如果由于某種原因開(kāi)發(fā)人員需要重新訪問(wèn)以前的代碼，他們常常想知道自己編寫(xiě)代碼時(shí)的想法。 不要感到驚訝：我以前也遇到過(guò)這種情況。 在這種情況下，我絕對(duì)希望我為代碼編寫(xiě)了良好的文檔。

如果你為代碼編寫(xiě)了良好的文檔，那么你可以快速了解代碼的底層，而不會(huì)產(chǎn)生太多疑問(wèn)，從而節(jié)省大量時(shí)間。 節(jié)省的時(shí)間可以用來(lái)完成更改。

好的文檔有哪些特征？

有幾個(gè)因素可以幫助您構(gòu)建良好的文檔。 一些最重要的因素如下：

1. 永遠(yuǎn)不要假設(shè)

不要假設(shè)如果您知道某件事，用戶也知道它，或者他們知道他們應(yīng)該知道什么。 無(wú)論用戶的熟練程度如何，從一開(kāi)始就解釋各種事情總是更好。

例如sublime text 3 js代碼格式化，如果您構(gòu)建一個(gè)插件，您可能會(huì)從 . 它展示了如何構(gòu)建 HTML、在哪里放置 CSS 和 CSS、解釋如何從頭開(kāi)始初始化插件，甚至在添加所有這些內(nèi)容后顯示完整的最終標(biāo)記，所有這些都寫(xiě)得很清楚。

最重要的是，文檔應(yīng)該根據(jù)用戶的思維過(guò)程來(lái)編寫(xiě)，而不是開(kāi)發(fā)人員。 以這種方式處理您自己的文檔將使您更好地了解如何組織自己的代碼。

2. 符合標(biāo)準(zhǔn)

添加與代碼內(nèi)聯(lián)的文檔時(shí)，請(qǐng)使用代碼的編程語(yǔ)言所期望的標(biāo)準(zhǔn)。 我們應(yīng)該始終解釋每個(gè)函數(shù)、變量和函數(shù)返回的值的含義。 下面是 PHP 內(nèi)聯(lián)文檔的一個(gè)很好的示例。

/**
?* Adds custom classes to the array of body classes.
?*
?* @param?array $classes Classes for the body element.
?* @return?array
?*/
function?body_classes( $classes )?{
??// Adds a class of group-blog to blogs with more than 1 published author.
??if?( is_multi_author() ) {
????$classes[] = 'group-blog';
??}

??return?$classes;
}
add_filter( 'body_class', 'body_classes'?);

以下是有關(guān)使用 PHP 和 CSS 格式化內(nèi)聯(lián)文檔的最佳實(shí)踐的一些參考：

：

CSS：

如果您正在使用它，我建議安裝它，它將用內(nèi)聯(lián)文檔整齊地預(yù)先填充您的代碼。

3.圖形元素

圖形元素應(yīng)該在文檔中更頻繁地使用，因?yàn)樗鼈儽任谋靖庇^。 這些媒介很有用，特別是當(dāng)您使用圖形界面構(gòu)建軟件時(shí)。 您可以添加方向元素，例如箭頭、圓圈或任何可以幫助用戶直觀地了解如何完成步驟的元素。

以下是 Tower 應(yīng)用程序中的示例，您可以從中汲取靈感。 它們很好地解釋了如何以比純文本命令行更容易理解的優(yōu)雅方式進(jìn)行版本控制工作。

4、分區(qū)

您可以考慮將文檔中的某些內(nèi)容包裝在項(xiàng)目符號(hào)列表和表格中，因?yàn)檫@使用戶可以更輕松地掃描較長(zhǎng)的內(nèi)容并更輕松地快速導(dǎo)航。

添加目錄并將文檔分成易于理解的部分，同時(shí)保持每個(gè)部分與后續(xù)內(nèi)容相關(guān)。 內(nèi)容應(yīng)該簡(jiǎn)短明了。 下面是一個(gè)組織良好的文檔的示例：

我們可以點(diǎn)擊目錄元素直接跳轉(zhuǎn)到對(duì)應(yīng)的內(nèi)容。

5. 修訂和更新

最后，文檔編寫(xiě)完成后，仔細(xì)檢查是否有錯(cuò)誤，并在必要時(shí)或當(dāng)產(chǎn)品、軟件或庫(kù)發(fā)生重大更改時(shí)進(jìn)行修改。 如果它沒(méi)有與產(chǎn)品一起定期更新，那么您的文檔對(duì)任何人都毫無(wú)用處。

如有侵權(quán)請(qǐng)聯(lián)系刪除！