程式碼是靈魂 註釋是心聲

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

相關文章