轉載地址：http://www.vaikan.com/what-does-this-code-do/
在SciPy 2010大會上，一位發言人給我們展示了幾段簡短的代碼，並且問我們每段代碼都是做什麼用的。代碼寫的很明瞭，但沒有提供上下文的註解。下面的就是這最後一段代碼：
def what( x, n ):
if n < 0:
n = -n
x = 1.0 / x
z = 1.0
while n > 0:
if n % 2 == 1:
z *= x
x *= x
n /= 2
return z這個測試是在這天快要結束時進行的，我有些累了。我說不出這段代碼是幹什麼用的。可後來我發現自己處於很尷尬的境地，其實這段代碼所實現的算法我是十分熟悉的。我曾經寫過相同的代碼，而且還寫在了博客裏。
這個事件使我改變了對“自我註解”程序的理解。沒有上下文的提示，你很難理解一段代碼是幹什麼用的，即使是很小一段。
有意義的變量名稱和函數名能給理解程序帶來很大幫助，但一句簡單的註釋帶來的幫助更大。我們不需要那些冗餘的註釋，就像解釋這行代碼x = 1.0 / x是取一個數的倒數，我們要的註釋是能解釋這段代碼是來解決什麼問題的。
這還有個例子，你認爲這段代碼是幹什麼的？
uint what()
{
m_z = 36969 * (m_z & 65535) + (m_z >> 16);
m_w = 18000 * (m_w & 65535) + (m_w >> 16);
return (m_z << 16) + (m_w & 65535);
}很明顯這段代碼是處理底層問題的 — 它只有一些操作 — 但我們完全不知道它是幹什麼的。
在繼續往下讀之前你最好盡力思考一下這段代碼。如果你放棄了，那我告訴你，上面的第一段代碼是來自這裏的，第二段代碼是來自這裏的。
在通常我們的面對面交流中，有很多的信息是來自口頭表達之外的。我們通常會認爲我們的語言表達是最重要的，但是我們的語調，面部表情，肢體語言等傳遞了更多的信息。程序源代碼跟這些很相似，我們通常會在裏面隱含着大量的其它信息。
假設你的同事Sam請你幫他審查一下他的代碼。工作中發生這種情況一般你能得到大量的上下文語境幫助；它們並不是網上的某個隨機的代碼片段。更特殊的是，你還對Sam所工作的項目有相當的瞭解。你知道Sam爲什麼希望你幫他看一下他的代碼。也許他想炫耀一下他引以爲豪的傑作，或者他希望你幫他找出一個bug。你在看他的代碼之前已經有了相當的瞭解。
但如果你是個接手人。Sam不幸被車撞了，你被要求在Sam出院之前維護他寫的代碼。你很可能會向他的同事抱怨，說他寫的代碼是如此的糟糕，但他的同事卻不理解你爲什麼要這樣說。他的同事會認爲Sam的代碼非常的清晰易懂。
再假設你是Sam接手人，而且在世界的另一端。你不能跟他的同事很好的交流，你只知道很少的上下文語境。在痛苦的折磨後，你把你修改的程序發回Sam的公司。你把你的程序註釋的非常充分，但Sam的同事卻抱怨你的代碼亂極了，你並沒把問題真正的解決。
共事共識比源代碼註釋更有價值。所以說替換一個程序員的代價是巨大的，即使是他走時留下的是註釋很好的程序。
[英文原文：LINK ]