代碼中到底應(yīng)不應(yīng)當(dāng)寫注釋？
當(dāng)很多前輩教育后輩應(yīng)當(dāng)多寫注釋的時(shí)候，當(dāng)網(wǎng)絡(luò)上充滿了有關(guān)程序員從不寫注釋的段子的時(shí)候，這是一個(gè)非常有爭(zhēng)議的話題。作為一個(gè)標(biāo)題黨，容我先修正一下我的觀點(diǎn)：我認(rèn)為如果代碼寫得足夠好，那么大多數(shù)注釋是多余的，我們應(yīng)該通過寫出更好的代碼來代替更多注釋。
注釋的確有其用途，但大部分情況下，程序員在濫用注釋。我是反對(duì)夾雜在代碼間的注釋的，我認(rèn)為注釋應(yīng)當(dāng)從代碼中獨(dú)立出來——通常被稱為文檔。
請(qǐng)看下面一段代碼。
/* /static/market/checkout.js
2014.7.2 create by orzfly
2014.7.29 update by jysperm: fixbugs
TODO: 這段代碼中注釋太多了，需要移除一些 -- jysperm
*/
var raw_products = req.query['products'].split(',');
// 商品 ID 的數(shù)組
var products = []
// 過濾每個(gè)參數(shù)
for(var i = 0, i < raw_products.length, i++) {
if (!raw_products[i])
return;
// 前端傳來的數(shù)據(jù)中居然會(huì)有空格
if (!raw_products[i].trim())
return
/* 2014.7.22: 現(xiàn)在可以使用非數(shù)字 ID 了
// 略過非數(shù)字條目
if (isNan(raw_products[i].trim().toFixed()))
return;
*/
products.push(raw_products[i].trim().toFixed());
}
// 總錢數(shù)
var sum = 0;
// 計(jì)算每個(gè)商品的總錢數(shù)
for(var i = 0, i < products.length, i++) {
// 從數(shù)據(jù)庫(kù)中查商品信息
var data = db.product.byID(products[i]);
// TODO: 誰來寫一下沒查到商品的情況
// 把商品的價(jià)格加到總錢數(shù)上， a += b 是 a = a + b 的縮寫
sum += data.price;
}
你居然花了一半的時(shí)間在讀注釋上面，這是多么浪費(fèi)生命的事情，在代碼中每加一行注釋，都會(huì)增加代碼的閱讀成本——即使閱讀者已經(jīng)了解了注釋所要傳達(dá)的精神；同時(shí)也會(huì)增加維護(hù)成本：修改這段代碼的人不得不連同注釋一起修改——而且你不能確定他到底會(huì)不會(huì)這么做。
所以只有當(dāng)非常必要的情況下，才應(yīng)該添加注釋，而且應(yīng)當(dāng)言簡(jiǎn)意賅。注釋不應(yīng)當(dāng)解釋一段代碼在做什么，因?yàn)檫@是每個(gè)合格的程序員都應(yīng)該知道的事情，而是應(yīng)該解釋這段代碼為什么要這樣做。
由此引出幾種明顯不應(yīng)該添加的注釋：
本應(yīng)由版本控制系統(tǒng)記錄的信息、對(duì)代碼的評(píng)論，以及不是很重要的 TODO.
代碼并不是全部，一個(gè)但凡靠譜一點(diǎn)的項(xiàng)目，都應(yīng)當(dāng)有自己的版本控制系統(tǒng)，除了記錄代碼差異之外，還應(yīng)該有工單和 Issue 的功能。
閱讀代碼的人通常不需要了解幾個(gè)程序員之間的恩怨，很多時(shí)候也不關(guān)心這段代碼的歷史，這些信息只會(huì)把代碼拖得越來越長(zhǎng)。
廢棄的代碼
被棄用的代碼應(yīng)該被刪掉，這些代碼會(huì)非常影響閱讀，而且它們一般又很長(zhǎng)。
在絕大多數(shù)情況下，被棄用的代碼不會(huì)重新派上用場(chǎng)，即使出現(xiàn)了少數(shù)情況，你也可以從版本控制系統(tǒng)中找到它們。
對(duì)變量和函數(shù)名的解釋
這種情況下顯然你需要一個(gè)更恰當(dāng)?shù)拿?，如果這個(gè)標(biāo)識(shí)符有一個(gè)比較小的作用于，你可以使用一個(gè)比較長(zhǎng)的名字以便容納更多信息。
例如上文中的：
products 應(yīng)改為 products_id
sum 應(yīng)改為 total_amount
data 應(yīng)改為 product_record
對(duì)語法的解釋，以及顯而易見的事情
例如上文中的「把商品的價(jià)格加到總錢數(shù)上， a += b 是 a = a + b 的縮寫」，這顯然是任何一個(gè)人都知道的事情。
也許有人愿意通過寫這樣的注釋來梳理思路：
// 過濾參數(shù)：
// 去掉 ID 里的空格
// 去掉非數(shù)字 ID
// 循環(huán)每一個(gè)商品：
// 去數(shù)據(jù)庫(kù)查記錄
// 把商品的價(jià)格加到總錢數(shù)上
但是當(dāng)代碼寫完的時(shí)候記得刪掉。
對(duì)邏輯塊的概括
例如上文中的「過濾每個(gè)參數(shù)」和「計(jì)算每個(gè)商品的總錢數(shù)」，這情況下通常是你沒有對(duì)邏輯進(jìn)行抽象，具體表現(xiàn)就是像下面這樣：
// 首先有 25 行代碼去做事情 A
// 然后有 5 行代碼去做事情 B
// 這里有 90 行代碼去做事情 C
// 最后有 45 行代碼去做事情 D
這導(dǎo)致你需要一些注釋來分割這四個(gè)部分。如果這四個(gè)部分都是一個(gè)函數(shù)調(diào)用的話，那么函數(shù)名本身就是對(duì)邏輯的一種解釋，讀者可以快速地找到函數(shù) B, 而不必在前 25 行中搜索做事情 B 的五行代碼。
綜上，我對(duì)這段代碼的改善意見如下：
var filterProductID = function(raw_products_id) {
result = []
raw_products_id.forEach(function(product_id) {
if (product_id and product_id.trim())
products_id.push(product_id.trim().toFixed());
});
return result;
};
var getPriceOfProduct = function(id) {
var product_record = db.product.byID(products[i]);
if (product_record)
return product_record.price;
else
return 0;
};
var products_id = filterProductID(req.query['products'].split(','));
var tatol_amount = 0;
products_id.forEach(function(product_id) {
tatol_amount += getPriceOfProduct(product_id);
});
雖然我在以一段虛構(gòu)的，刻意編造的代碼來佐證我的觀點(diǎn)，但我相信在實(shí)際的項(xiàng)目中，同樣可以通過改善代碼來減少注釋，而且總體上來講會(huì)節(jié)約更多的時(shí)間和精力。
相關(guān)文章
2018年GitHub賬戶注冊(cè)圖文教程(github從注冊(cè)到使用)
Github是最流行的代碼庫(kù)，里面存儲(chǔ)著豐富的優(yōu)秀的開源代碼。不僅如此，作為一款免費(fèi)的代碼存儲(chǔ)利器也是流的一逼，支持各種編程語言，代碼顯示效果堪稱完美，可以隨時(shí)隨地查看自己記錄的筆記2018-02-02
安全校驗(yàn)Session驗(yàn)證碼并避免繞開驗(yàn)證碼攻擊
校驗(yàn)驗(yàn)證碼的Session是否為空或者校驗(yàn)用戶輸入的驗(yàn)證碼是否合法，構(gòu)造安全表單的關(guān)鍵就是永遠(yuǎn)不要相信用戶的輸入2012-01-01
Express 是一個(gè)簡(jiǎn)潔而靈活的 node.js Web應(yīng)用框架, 提供了一系列強(qiáng)大特性幫助你創(chuàng)建各種 Web 應(yīng)用和豐富的 HTTP 工具，如果你不會(huì)jJava or Python等后端，使用 Express可以幫助我們快速地搭建一個(gè)完整功能的網(wǎng)站2021-08-08
gaussdb 200安裝 data studio jdbc idea鏈接保姆級(jí)安裝步驟
這篇文章主要介紹了gaussdb 200安裝 data studio jdbc idea鏈接保姆級(jí)安裝步驟,本文通過圖文并茂的形式給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2021-08-08
數(shù)組都是從0開始。javascript是arrayname[i]，而vbscript是arrayname(i),javascript的字符串還是從0開始,asp的字符串下標(biāo)從1開始2013-03-03
今天是開篇，得要吹一下算法，算法就好比程序開發(fā)中的利劍，所到之處，刀起頭落2013-11-11
Git中的git?push命令用于將本地倉(cāng)庫(kù)的改動(dòng)推送到遠(yuǎn)程倉(cāng)庫(kù),是協(xié)同開發(fā)中的重要工具,在團(tuán)隊(duì)合作中,使用git?push和git?pull可以有效維護(hù)項(xiàng)目同步,避免沖突,推送時(shí)若遇到?jīng)_突需先解決后再進(jìn)行推送,需要的朋友可以參考下2024-09-09
這篇文章主要介紹了Git?的?rebase?命令使用方法,接下來，我們使用rebase命令，其命令一般形式為git?rebase?feature，即表示在?master?分支上執(zhí)行rebase命令，將?feature?分支的代碼合并到?master?分支,本文給大家介紹的非常詳細(xì)，需要的朋友可以參考下2022-05-05
一文詳解VSCode安裝配置使用(最新版超詳細(xì)保姆級(jí)含插件)
安裝VScode就很簡(jiǎn)單了,一路NEXT就可以了,重點(diǎn)是配置使用以及插件推薦,這篇文章主要給大家介紹了關(guān)于VSCode安裝配置使用的相關(guān)資料,本文是最新版超詳細(xì)保姆級(jí)含插件,需要的朋友可以參考下2023-05-05
IDEA2019.3在Plugins中搜索不到translation的解決
這篇文章主要介紹了IDEA2019.3在Plugins中搜索不到translation的解決，文中通過圖文的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2020-06-06