大型公司的代碼注釋是怎樣的？
吐槽下實習單位，，整個函數一個注釋都沒有。。。
也可能是因為命名很規範的原因吧
一般來說，我們的注釋，要麼是使用文檔，要麼是告訴你為什麼要這麼設計。
而且好的設計都是沒有注釋的，因為一個合格的工程師當然要理解好的設計為什麼好。我們只注釋那些設計不好但是又不得不這麼做的。
當然了，這並不是什麼好事，大家不要學。我相信大部分公司都不敢因為一個程序員看不懂代碼就開除（逃貼一個我看過的某大公司代碼里的注釋，國內知名遊戲公司，現已倒閉，不過代碼還是很好看的
public var count:int = 9;//這裡就他（和）媽（諧）是9不是13，王小明（名字不記得了）你再瞎 改老子代碼老子弄死你——劉日天（名字不記得了）
看，這種地方應該加註釋
----------轉一個我之前的回答，針對國內普遍程序猿的English還不如Java水平高的情況--------------
注釋什麼時候寫？
寫代碼之前寫一部分，調試時候寫一部分，寫完代碼之後補一部分- 寫代碼之前的：等於是你的提綱，也是後來人理解你代碼的途徑
//這裡取出兩個用戶Tom,Jerry
//如果Tom年齡大，則返回true
//遍歷列表，查找兩個人的同類
//如果Tom的同類多返回true
//如果Tom個子高返回true
- 調試時候的：
//print tom.age //不應該大於lily.age
調試時候你列印的變數，可能是後來人改代碼時的關鍵檢查點，可以考慮一部分變成注釋
- 寫完功能後：對於不好理解的地方再補點注釋，原則是後人改代碼時候一眼就看清你的思路
- 重構/複查代碼時候：如果你倆禮拜之後對著一個你寫的/別人寫的地方琢磨了半天不知道啥意思，要麼你改演算法，要麼至少留點注釋
- 對於英文不好的同學，就不要在注釋里強秀英文了……過倆月自己都看不懂了
- 變數/類名字如果是你用有道詞典或者百度查出來的單詞……麻煩在聲明的地方加個中文注釋
你聽說過用注釋來實現代碼版本控制的么？
這就是滙豐投資部門的開發團隊近三十年來一直在做的事情。
這個部門從創立初始就一直在用IBM提供的iSeries平台，當時是沒有配套的代碼管理工具的，結果早期的滙豐開發團隊就想出這麼一個主意：把需要修改的舊代碼全部注釋掉，然後再下面加上新代碼。每一次的修改都有一個指定的序號，這個序號會被加到被修改過的代碼處以標記修改的內容。這麼做的結果就是一份源代碼里有大量的內容是沒用的，它們的存在僅僅是為了保留歷史修改記錄。這些被注釋掉的代碼和真正的注釋（前提是有的話），真正的代碼混雜在一起，讓人看不出哪些是代碼哪些才是注釋。看這些舊代碼真心是屎一樣的體驗，更不用提每次搞開發都要先費力注釋掉舊代碼。
最神奇的是後來IBM提供了代碼管理解決方案，能實現和SVN一樣的效果，但是滙豐為了保持代碼一致性居然還讓開發團隊沿用舊的習慣，僅僅是在一個不同的埠作業。那你花錢搞這麼一套解決方案回來有啥用啊？拿蘭博基尼當拖拉機使也不過如此了。
利益相關：前滙豐碼農任何公司只要大了，就沒有規範而言。完全取決於team。
特別是十年以上的公司，什麼代碼都有。首先，注釋是必要的，而且肯定要有的。
除了注釋之外，還有一種叫做文檔。但是編碼的時候，一般不去寫文檔。文檔這種東西設計階段基本都做完了，大致闡述一下項目的架構，模塊的劃分之類的，同時可能還要介紹項目的幾個關鍵點。
注釋這東西，大部分都是給別人看的，有時候自己也會看看（過了很久之後自己忘記了這段到底是什麼東西）。因為項目團隊中肯定有其他人，大家都要合作的，並且萬一哪天出bug了而你恰好不在，別人也能幫你解決。
那麼，到底該怎麼做注釋呢？
各個公司肯定有各自的規範，大家還是按照規範來吧。當然，我回答問題也不是這麼不負責任的。
個人觀點，只是經驗之談，歡迎來噴 ！1、在類級別，方法級別上最好加上注釋。特別是那些邏輯複雜的，難以用一句話描述清楚的內容，最好加上注釋，講清楚這個類，或這個方法是用來幹嘛的，有什麼需要注意的地方。這個注釋很重要，特別是這些代碼還要被其他人使用的時候，加上說明會方便很多。
2、在某些容易留坑的地方，最好加上注釋。這種地方很多時候是因為圖省事，或者沒時間等原因，只能暫時這麼做，但是需要提醒使用者注意。或者懷疑隊友水平沒那麼高，理解不了你的代碼，某天來修改代碼並且容易改錯。或者是因為這段代碼『特立獨行』，不是按照常規方式，你自己在這裡耍了小聰明，或者用了自己設計的一些技巧性的東西，怕別人看不懂。3、涉及到業務邏輯的代碼，比如某些欄位需要加說明，之類的。有些業務的東西，確實不是一兩句代碼就能扯清楚的，這種東西，加個注釋就好了。4、因為修復某個bug而加進去的代碼。改bug，特別是改別人的bug的時候，如果不是進行大規模的重構，而是往裡面加小段代碼打補丁的時候，最好加上注釋，否則這段代碼很奇怪，並且容易看不懂。記住最好留上你的名字，不然後人看這個代碼都不知道該去罵誰，hiahiahia~。當然，有人也說了，最好的注釋是代碼本身，這句話沒錯。但是，什麼事情也有例外，而且有些東西也不是你一句代碼一句變數名能說明清楚的，有些設計也是需要做出妥協的，並不能做到『好的設計』。這時候最好用注釋解決。主要宗旨就是：怎麼簡單怎麼來。
拿個例子來說吧，當你寫的某個方法被其他方法調用了，而你這個方法實現了某項功能，修改了某個狀態量，並且返回值有多種情況，並且在某些情況下會拋出異常。恰巧，某天整個模塊出問題了，然後大家開始排查問題了。假如你這個方法沒寫注釋，那麼完了，其他人要一步一步往裡面讀你的代碼，理解裡面的意思。假如你寫了注釋，描述了方法的作用，返回值對應的情況，拋出異常的原因，我想讀代碼的人應該很快就能判斷需不需要再往裡面看你的代碼的細節了。
工程這種東西，沒有絕對性，更多的是在多個因素中做出妥協，達到整體的優化。注釋也是，沒必要為了注釋而注釋，也不能不寫注釋。但是我覺得，如果你沒辦法保證自己不留坑的話，還是把注釋加上吧，為了您和他人的健康著想。
好的代碼是自注釋的，尤其是python這樣邏輯密度高的代碼，優美的代碼不需要注釋。
反過來，有太多語法細節和邏輯分支的代碼，不注釋會死人的。
所以，大公司是什麼代碼注釋風格，取決於這是什麼結果的項目。我們公司代碼沒有注釋的，有也只是 極少部分的 英文注釋。對此我問了主程，他告訴我幾個原因。第一，屬性，方法，類的命名全部都有規律，能看懂英文就知道這個屬性幹嘛的，絕對不會是那些什麼 String a1 = "身份證號碼";List&
當然！！！！我是反對這樣的做法的！！！！！
你英文好不代表我英文好啊！！！每次也是打開翻譯在隔壁！！！寫完注釋也是默默的刪掉！！！有時候百度翻譯的不正確還會被主程調我寫的介面的時候，會說這個英文名詞不是這個，你這個是形容詞，而且不應該用這個單詞，之類的。嗯，間接提升了英文水平？然並卵！吐槽：
// 將1賦值給i
int i = 1;每次看到這樣的注釋，我的內心都是崩潰的。足夠好的代碼不需要注釋，只有一些太過詭異的需求和quick fixes需要。記住注釋的目的是讓人看懂，不要為了注釋而注釋。
寫工具可以不寫注釋，只要知道輸入輸出即可，但是大部分程序員還是在寫業務功能吧，也不寫注釋，我覺得是不是有些心機在裡面：我噁心了那麼久理清楚的業務，幹嘛要告訴你，這裡出問題只能找我。提升自己那可憐的存在感
我個人也覺得好的設計和命名基本不用注釋
注釋只用於實在難以理解以及少數需要特別注意的地方
當然 頭文件特別是寫給別人的庫的頭文件可以寫一點說明性注釋 作用類似於文檔
Cpp中我是覺得注釋越少越好 需要注釋的地方就應該封裝成函數小塊塊閑著沒事看了看BIGWORLD引擎，整個人都哭了。文檔不全不說，函數內部相互引用，各種類相互引用。注釋只有部分類的啊，而且只說明這個類是幹什麼的啊？類的成員函數和類的成員變數有什麼作用完全不提啊。有個成員函數啊，叫amount啊，amount個鬼啊，還有個叫add的啊，還有個叫traval的，旅你妹的行啊！
因為要求用英文注釋，我一般都寫拼音來注釋……又方便，我還能大概看得懂
//別刪這行刪了會掛雖然我也不知道為啥
從別的地方看到的
C++大概用的比較多的那些庫會有很完善的「對外」注釋吧……即寫在.h里的，文件級別和函數級別的注釋。包括簡單的介紹，使用範例，注意事項之類的。說「對外」是因為這是寫給這個庫的使用者（其他組的人）看的。
相對的.cc里的「對內」注釋就少很多了。只有某一段邏輯特別糾結或者很難只從代碼就看出在幹嗎的情況下會寫個注釋用來說明。什麼地方冒出來一個 //TODO(ldap) 結果blame一看是好幾年以前的，然後那個人也早就離職了，這樣的情況也很常見。
.cc里的內部實現邏輯其實也沒有必要寫太詳細的注釋。畢竟所有的代碼都可以blame看當時對應的changelist的具體說明和changelist對應的issue，甚至還可以找到具體的設計文檔，這樣就可以知道這行代碼當初加進來是為了實現怎麼樣的一個特性，或者修復了一個什麼錯誤。
Java寫的不多。印象中是除了那種「顯而易見」的函數（getter/setter那種程度的顯而易見），其他都必須有javadoc。代碼通過命名盡量做到自注釋，注釋大部分用來解釋設計意圖。題主可以去看下《代碼大全》《代碼整潔之道》《編寫可讀性代碼的藝術》這幾本書關於注釋的章節。
有些代碼一定要寫注釋，如果你不寫注釋的話，下一個接手修改你的代碼的時候會被罵傻逼。
見過這麼一行注釋// 該控制項用runtime修改了屬性,如果你看不懂,聯繫我的QQ:123123123
像我們這種依賴node的前端項目，注釋都是按照jsdoc的規範寫的，可以直接生成文檔
雖然基本沒人看……
個人感覺，寫代碼之前把設計文檔規規範范的寫好了，代碼中不需要多少注釋的
像我這種英文水平有限，變數名方法名不一定自說明的還是老老實實寫下注釋，提供大概思路，尤其是複雜的業務邏輯
early-microsoft-code-riddled-with-hidden-jokes
http://mobile.news.com.au/technology/home-entertainment/early-microsoft-code-riddled-with-hidden-jokes/story-fnjwukfu-1226866435651推薦閱讀：
※變數命名長的程序會不會比變數命名短的程序運行速度慢一些？
※習慣聽歌寫代碼 有必要買個好耳機嗎？
※適合在校it男敲代碼用的鍵盤。什麼都不懂但想送他鍵盤？
※如何實施代碼重構？
※作為程序員你寫過的最漂亮的代碼是什麼？
TAG:代碼 |