• 对于初学者,很不注重这方面,所以代码写出来,人家看不懂,这个给后来人带来很多不便,如果多花的时间在命名,注解上,对自己或对别人都会有好处的,毕竟人不是机器人,久了都会忘记…
  • 今天在网上看到了一篇2003年的关于PHP标准的翻译,但是我觉得对其他程序应该也使用,特别是初学者,真的要培养这方面

译文: http://twpug.net/modules/smartsection/item.php?itemid=1
原文:

搜尋關鍵字﹝Gotcha Keywords﹞
:TODO: 主題
表示這裡還有工作尚待完成,不要忘記了。
:BUG: [bugid] 主題
表示這裡有一個已知的臭蟲,並加以解釋,或許再給一個臭蟲編號。
:KLUDGE:
當您很笨拙的完成某件事情時,就明白的說出來,並說明您下次想採取 怎樣不同的方法去做,如果您還有時間的話。
:TRICKY:
告訴別人以下的程式碼是非常有技巧的,請不要不加思索的修改它。
:WARNING:
要注意某件事情。
:PARSER:
偶爾您必須設法解決程式語言剖析器所產生的問題。請加以註明。這個剖析器的 問題終會被修正。
:ATTRIBUTE: value
這是個一般格式,說明該註解所內含的屬性。您可以創造您自己的屬性,它們 也會被析取出來。
搜尋格式﹝Gotcha Formatting﹞
將搜尋關鍵字放在註解的最前面,亦即第一個符號。
註解也許會包含好幾行,然而第一行必須是獨立而有意義的簡要說明。
作者的名字與註解的日期也應該寫在註解裡面。這兩項資訊雖然也可以 在原始碼的倉儲裝置中找到,但是這或許需要一段時間才能查明這段註解 到底是誰、在什麼時後所加上去的。通常這會浪費許多時間去搜尋。 將日期資訊寫在註解裡面,可以讓其他程式設計師在做決定時有所依據。 將作者資訊寫在註解裡面,可以讓我們知道應該找誰問問題。
範例
// :TODO: 年月日 960810: 執行效率問題
// 其實我們應該在這裡使用雜湊表,但是現在先使用線性搜尋。

// :KLUDGE: 年月日 960810: 不安全的強制轉型
// 這裡我們需要作一個強制轉型,以回復原本的衍生型別。或許我們應該
// 使用一個 virtual method、或是使用 template。

转载请注明:韦旭红的点点滴滴 » 关于写程序的一些标准