我個人的方法與變數取名經驗

少用Filter這方法名稱,是Filter掉什麼?留下什麼?
Filter約定成俗,常見是有保留的意思。
其實可以用其它單字,如select等等。
避免用filter
filter(year>2011)
是選取還是排除?常代表的是選取比較多
如果是選取,可以用select,如果是排除,可以用exclude

閉區間的方法or變數:用first,end來取名
半開放區間的方法or變數:用begin,end來取名
區間,如一個方法叫getRange(2,4)
到底是會抓出2,3,4,還是2,3?
通常若是抓出2,3,4的,叫閉區間 ,會用first與end
若是2,3,叫半開放區間 ,會用begin與end, 表示有起點,而不會含終點

來Size取名不好,是指什麼的大小?
delay可以改成delay_secs
size可以改成size_mb
limit可以改成max_kbps
時間最好加上單位,大小最好加上mb,kb,bytes等

像gettime,到底回傳是秒還是毫秒?
gettime_ms就又更好

password,可以改成plainttext_password
html_utf8,有編碼
但不應該所有的變數都要補上_utf8,在容易被誤解的地方補上。

我曾見過
avail,valid充滿了整個class,
當這兩個單字放在同一class,真的容易誤解。

無意義的縮寫
BackEndManager改取作BEManager,
Workspace縮寫成WS只縮寫成這樣可以減少它的困擾嗎?
連函數都不註解。自己發明一些奇怪的縮寫,
讓程式看起來神密兮兮的用處是什麼
讓別人覺得自己很厲害?
這些程式設計師背後的心態是什麼?

快速區分出是成員變數還是全域、區域變數。
成員變數的前綴字可以補個m,或是_

未處理的補上raw

一字多義。
!right是代表?不對,還是不是左邊?

clip(string str,int length)
到底是從尾端刪除length還是
只留最尾端的資料?

length到底是bytes數量,還是字元數量?還是單字數量?

有邊界的值,如你限定超過十項要有警告。
就要寫好max_xxx。
讓人一清楚看見此變數有極值。

布林值前面可用前綴字
is, has,can,should

bool read_pawword=true;
到底是需要讀,還是已讀完?

避免否定敘述
如 bool disable_ssl
而該用bool use_ssl=true。

通常人會預期get與size是輕量級的方法,應該幾秒鐘就回覆。
c++在非常早期的list容器有個關於size的問題。
當時size調用時,並不是個常數。
而真的把list串列整個走完。
當不是個常數時,應該要加上動詞,如寫成countsize,
現在的c++的list的size的複雜度現在已經是O(1)

—————註解—————–

好程式> 壞程式+註解

讓變數名稱本身就是註解。
變數名字取好就不用註解。

程式的文化是會漫延的,不註解,大小寫隨便,一堆val。
但漂亮的程式碼會有啟發性,還會激發別人去改善自己的程式碼

註解:想像讀者需要知道的東西。
註解要有價值。不要註解能很快從程式碼知道的事實。
有些不要註解,直接改掉名稱。
不要用註解補救不好的名稱。
函數名稱就要說明函數的意圖,self-documenting。
好的函數名稱比好的註解更為重要

導演評註:director commentary。
記下寫程式時重要的想法

少了註解,讀者可能會害怕改動雜亂的程式碼。

FIXME,已知的問題
HACK:承認解法方式不夠優雅
XXX:危險
TODO:作者未處理的部份
todo:小寫,小問題

註解常數為何會是特定數值的原因
設了一個莫明奇妙的常數在其中,卻沒有說明
//經實測多次調整,這效果最好
image_quality =0.72
應該要這樣註解,
而不是莫明一個常數在那裡

廣告

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com 標誌

您的留言將使用 WordPress.com 帳號。 登出 /  變更 )

Google+ photo

您的留言將使用 Google+ 帳號。 登出 /  變更 )

Twitter picture

您的留言將使用 Twitter 帳號。 登出 /  變更 )

Facebook照片

您的留言將使用 Facebook 帳號。 登出 /  變更 )

連結到 %s