iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 24
1
Mobile Development

如何用 Laravel 撰寫難以維護的專案系列 第 24

[Day 24] 另一種形式的文件:談談難以維護的註解

除了一般的文件以外,更多我們常使用到說明程式碼的方式,就是使用註解。

今天我們來談談怎樣的註解可以讓專案更難維護。

不寫註解

不寫註解。

註解範本

有的 IDE 會提供註解範本,大量使用這類範本,但是不要填寫裡面的內容。這可以加入很多沒有意義的註解文字,讓之後的工程師要在更多的程式碼裡面找到功能。

如果有人覺得註解範本產生的註解有問題,提議那就不寫註解。

在註解裡說謊

和文件一樣,你只要不去維護註解,隨著時間過去和需求改變,久而久之註解和實際的需求越來越無法吻合,你的註解就會說謊了。

為顯而易見的東西寫註解

在程式碼裡散佈像是 /* i 加上 1*/ 這樣的註解。

不過,絕對不對這段程式碼實際在做什麼這類的事加上註解。這種註解對維護工程師的幫助太大了,我們要儘量避免。

政府官員式註解

以下是一個「政府官員式」的註解範例:

/**
* 做 snafucated
* /
public function makeSnafucated() {

}

然後沒有任何地方定義 snafucated 到底是什麼意思。


上一篇
[Day 23] 再談談技術文件:怎麼撰寫文件讓專案難以維護
下一篇
[Day 25] 程式碼的撰寫風格,來談談 PSR
系列文
如何用 Laravel 撰寫難以維護的專案30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言