程式碼是靈魂 註釋是心聲

codeceo發表於2014-11-27

　　在以前一些關於程式碼註釋的文章中，我發現，你不需要的註釋才是最好的註釋。不要急著批判，請允許我闡述一下。首先程式碼應該儘量地簡潔，儘可能地做到不需要依賴註釋就可以理解。只有那些真的沒法更易於理解的程式碼，才需要我們新增註釋。

　　有一本非常經典的書叫《Structure and Interpretation of Computer Programs》（《電腦程式的結構和編譯》），最初發表於1985年，在序言中就表明其觀點：

程式必須能便於我們閱讀，讓機器執行只是附帶的。

　　Knuth也在他1984年發表的經典論文《Literate Programming》（《文學程式設計》）中秉持了類似的觀點：

我們應該轉變傳統的思維，程式不再是告訴計算機做什麼的指令，而是向人類描述如何讓計算機做事情的文字，程式設計像寫文章一樣。

　　文學程式設計關注的主要是展現精緻的風格。程式設計師應該像作家一樣，認真地選擇變數名，並解釋每個變數的意思，努力寫出易於人腦理解的程式。

　　如果你寫出來的程式碼，既能被其他程式設計師理解又能成功編譯，那麼需要新增註釋的地方肯定就不會很多。關於使用註釋作為輔助工具，下面就是一個頗具代表意義的例子：

　　這段程式碼取自一個已經使用多年、閉源了的系統。

float _x = abs(x - deviceInfo->position.x) / scale;
int directionCode;
if (0 < _x & x != deviceInfo->position.x) {
    if (0 > x - deviceInfo->position.x) {
        directionCode = 0x04 /*left*/;
    } else if (0 < x - deviceInfo->position.x) {
        directionCode = 0x02 /*right*/;
    }
}

　　上面的程式碼等同於下面的程式碼，但是下面的程式碼可讀性更高。

static const int DIRECTIONCODE_RIGHT = 0x02;

static const int DIRECTIONCODE_LEFT = 0x04;

static const int DIRECTIONCODE_NONE = 0x00;

int oldX = deviceInfo->position.x;

int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;

　　需要注意的是，註釋的越多並不意味著程式碼的理解性更強。當然在本案例中並沒有涉及到這一點。上面的註釋——如果你注意到的話——使得程式碼更加顯得凌亂不堪。有時候，註釋得越精簡程式碼的可讀性才越高。特別是在你必須更換使用其他符號名的情況下。

　　雖然我們能無限次地重構和精簡程式碼以避免寫繁冗的註釋，但是表述自己的思考過程的方式卻是有侷限性的。

　　無論最後你呈現的程式碼是有多麼的簡潔和清楚，程式碼也不可能完全自文件化。但是程式碼永遠也不可能取締註釋的存在。正如Jef Raskin所說：

　　[程式碼]無法解釋如此寫程式以及選擇該方法的原因。從[程式碼]上我們也看不出選擇某些替代方法的理由。例如：

/* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */

　　在A開發人員看來完全顯而易見的東西，可能在B眼裡完全就像霧裡看花一樣。所以我們在寫註釋的時候，也要考慮到這一點：

　　下面這個可能你一清二楚

$string = join('',reverse(split('',$string)));

　　反轉字串，但是要如何才能插入到

# Reverse the string

　　Perl檔案中呢？

　　的確，這一點都不難。歸根究底，程式碼只會告訴你程式是如何工作的，但是註釋則能說明工作的原因。所以，下次你寫程式碼的時候，不妨在這兩個方面給你的同事做個榜樣。

　　英文原文：Code Tells You How, Comments Tell You Why via:codeceo

相關文章