建站
咨詢
售后
建站咨詢
新聞中心
先讓我們來聽一個(gè)令人惡心的例子。
創(chuàng)新互聯(lián)科技有限公司專業(yè)互聯(lián)網(wǎng)基礎(chǔ)服務(wù)商，為您提供服務(wù)器托管機(jī)柜，高防服務(wù)器，成都IDC機(jī)房托管，成都主機(jī)托管等互聯(lián)網(wǎng)服務(wù)。
你看到 問題 F00-123 被解決了。這是關(guān)于一個(gè)你自己很 熟悉的子系統(tǒng)的 Bug，所以直覺告訴你造成這個(gè) Bug 最可能的原因。為了證實(shí)你的懷疑，你決定看看這個(gè) bug 是怎么被解決的。你花了很長(zhǎng)時(shí)間搜索了整個(gè)版本歷史，直到把這個(gè) bugfix 的范圍縮小到了 4 個(gè)連續(xù)的提交，它們分別的提交信息是： dao 小調(diào)整(dao tweaks)、 moar、 Fixes， 還有 刪除一些調(diào)試信息(remove debug stuff)。每個(gè)提交的修改集看起來都很大，多達(dá)十幾個(gè)文件的幾百處修改?！拔移H尼@#$%%^&”，你準(zhǔn)備罵娘但還是停住了，沒有罵出你腦中那句最難聽的粗口。“這個(gè) bugfix 不應(yīng)該超過三行代碼!”。
上面的例子聽起來是不是很熟悉咧？很多開發(fā)者僅僅只把版本控制系統(tǒng)當(dāng)成是一堆文件的備份。這些歷史備份除了可以讓你取回某個(gè)時(shí)間點(diǎn)上的文件內(nèi)容之外，沒有任何其他用處。下面這些建議可以幫你把你的版本控制系統(tǒng)從一個(gè)備份系統(tǒng)，變成用于溝通和文檔編寫的一個(gè)寶貴的工具。
1. 每次提交只做一個(gè)修改
如果你在一次提交中修復(fù)了 F00-123和 F00-233、重構(gòu)了一個(gè)類、界面上添加了一兩個(gè)按鈕、還有把整個(gè)項(xiàng)目文件中的 tab 改成空格，那么基本上沒有人能 review F00-123 的 bugfix，只有你自己才知道哪些修改屬于那個(gè) bugfix 的一部分，但是一周以后很可能你自己都忘了。
要是一周以后你發(fā)現(xiàn)原來的那個(gè) bugfix 導(dǎo)致了另外一個(gè)更嚴(yán)重的問題那你就完蛋了，你不能使用 hg backout或者 git revert來撤銷你的修改，因?yàn)槟菢訒?huì)把除了那個(gè) bugfix 之外的所有修改都撤銷掉，也意味著你一周的努力白費(fèi)了。
上面這種問題的解決辦法就是“每次提交只做一個(gè)修改”，對(duì)于怎么樣才算是“一個(gè)修改”沒有任何硬性或者既定的規(guī)則，但如果你能夠用一個(gè)句子并且不用用到“和”這個(gè)字來描述你所做的所有事情，那么你算是做到了。
分布式版本控制系統(tǒng)其中一個(gè)很好的功能就是，如果你的工作目錄中有很多相互之間沒有關(guān)聯(lián)的修改，你可以用它來幫你 收拾好你的爛攤子(clean up the mess you’ve made)，但是***別在一開始就搞出一個(gè)爛攤子。在你開始修改代碼之前，先確定你想干什么和你想怎么做，然后再認(rèn)真把關(guān)注點(diǎn)放在你想修改的那個(gè)點(diǎn)上。
在沒有想出怎么改進(jìn)某塊代碼之前，貌似不太可能去修改那塊代碼。你發(fā)現(xiàn)了 bug、看到了一些糟糕的代碼、還有一些你很好奇想進(jìn)一步了解的東西。無論你多么想去做，千萬別被轉(zhuǎn)移了注意力。這些發(fā)現(xiàn)非常有價(jià)值，用一個(gè)筆記本或者一個(gè) TODO 文件把他們 寫下來(jot them down)，在完成當(dāng)前任務(wù)之前不要想去解決那些問題。
這個(gè)不僅僅是關(guān)于更好地提交。當(dāng)你沉浸在解決某個(gè)編程問題里面的時(shí)候，你的頭腦充滿著關(guān)于這個(gè)問題的一堆細(xì)節(jié)，如果這個(gè)時(shí)候你跳去想一些其他問題，那么你會(huì)忘了原來那個(gè)問題的細(xì)節(jié)，再回到原來那個(gè)問題需要花一些時(shí)間。你需要 減少任務(wù)切換(minimize task switches)來提高你的工作效率。
當(dāng)然有些時(shí)候你會(huì)發(fā)現(xiàn)在沒有解決某些其他問題之前，你很難完成當(dāng)前的任務(wù)。這個(gè)時(shí)候最簡(jiǎn)單的方式就是使用 hg shelve或者 git stash把你當(dāng)前還沒有完成的修改暫存起來，把兩個(gè)問題的修改分開，提交那個(gè)被依賴的修改，再回到你原來的任務(wù)上面去。
2. 每次提交要包含完整修改
如果一個(gè)修改分布到了幾個(gè)提交里面，那么這個(gè)修改也是很難 review 的。通常這是因?yàn)樵谕粫r(shí)間解決太多問題導(dǎo)致的，如果你吃不了那么多，卻啃了那么多，那么在你想保存其中的某些修改的時(shí)候，你會(huì)發(fā)現(xiàn)大部分的修改都是未完 成的。同一時(shí)間關(guān)注太多問題會(huì)導(dǎo)致***需要很長(zhǎng)時(shí)間才能夠提交完整的修改。（原文是：Focusing on one task at a time takes you a long way towards committing complete changes. 但我覺得作者的原意應(yīng)該是：Focusing on too many tasks at a time takes you a long way towards committing complete changes.）
有些修改需要花很長(zhǎng)時(shí)間，所以如果中間在某個(gè)點(diǎn)上你搞 錯(cuò)了，重頭再來你肯定折騰不起，所以你需要在過程中保存一些中間版本。幸好分布式版本控制系統(tǒng)都允許你保存很多中間版本但是***只提交一次修改到中心版本 庫(central repository)，你可以提交任意多次的中間版本，在***使用 hg histedit或者 git rebase把多次的中間版本合并成一個(gè)修改集。
另外一種，也是我個(gè)人比較喜歡的方法，因?yàn)樗阎虚g版本和***性的修改版本分開了，這種方法使用 Git 的 index，或者 Mercurial Queues 中的一個(gè) patch 來保存最近一次正確的（沒有 bug 的）中間版本，每次你做了新的修改你都更新這個(gè) index/patch，如果你犯了個(gè)錯(cuò)誤，你就可以使用他們恢復(fù)你的工作目錄了。I like to think of it as a one-slot quicksave for version control.（譯注：這句只可意會(huì)，我不知道怎么翻。）
3. 寫好注釋，說明你修改了什么
像“修復(fù)(Fixes)”、“提交(Commit)”這樣的提交信息沒包含任何有用的信息。如果別人想看看版本歷史，像這樣的提交信息只會(huì)逼他們?nèi)タ赐?所有的代碼修改，看代碼是很費(fèi)時(shí)費(fèi)力的。寫這樣一個(gè)簡(jiǎn)短但表達(dá)不清晰的提交信息，可能是省了你一分鐘時(shí)間，但是卻浪費(fèi)了其他人幾個(gè)小時(shí)。
一個(gè)好的提交信息可以讓看的人清楚代碼的哪一部分被修改了，是怎么被修改的，他們也不需要去看你的代碼：
- SomeClass: use bleh instead of xyzzy in someMethod (fixes FOO-123)
4. 注釋說明為什么做這個(gè)修改
假設(shè)每次修改代碼都有一個(gè)很好的理由/原因，但如果這個(gè)理由/原因被沒有記錄下來，那么整個(gè)代碼庫(codebase)將面臨以下風(fēng)險(xiǎn)：
- 其他開發(fā)者不明白為什么原代碼是那樣寫的。當(dāng)他們修改代碼的時(shí)候，他們可能會(huì)引入一些原作者已經(jīng)發(fā)現(xiàn)或者避免的問題。
- 其他開發(fā)者認(rèn)為原代碼那樣寫肯定是有（好的）原因的，所以***別動(dòng)它。他們把這些代碼看成是一個(gè)黑盒，然后加各種復(fù)雜的 workaround，避免修改原代碼。***導(dǎo)致這個(gè)代碼庫變得臃腫，代碼變得難以看懂。
如果你有足夠的理由有必要破壞一個(gè)項(xiàng)目的規(guī)范或者約定，那一定要把這個(gè)理由作為注釋寫在你的代碼里面：
- - xyzzy (bars); + // Our bars are already sorted, so bleh is much faster than xyzzy + bleh (bars);
如果你的代碼遵守了規(guī)范，并且你的代碼沒有什么微妙(subtleties)的點(diǎn)需要注意，那就沒有必要把你的文檔注釋寫在代碼里面。但仍然有必要讓人知道為什么新代碼優(yōu)于舊代碼（尤其是當(dāng)新代碼引入了一個(gè)新問題），所以還是要把原因?qū)懺谔峤恍畔⒗锩娴模?/p>
- SomeClass: Don't flush caches in someMethod The caches are flushed automatically at the end of each request.
如果一個(gè)修改解決了一個(gè)已知問題，確保在提交信息里面帶上 ticket 號(hào)（bug 追蹤系統(tǒng)中的 ticket），以便其他開發(fā)者在看版本歷史的時(shí)候能夠清楚地知道是在什么情況下做出的這個(gè)修改。
5. 不要提交被注釋掉的代碼
我沒有辦法理解提交被注釋掉的代碼背后的理論依據(jù)，我假設(shè)這是為了保存舊代碼，以防新代碼不能正常工作，但這種做法很莫名其妙，最開始我們使用版本控制系統(tǒng)不就是為了保存舊版本嗎？！
為什么要注釋掉這些代碼？這些代碼能運(yùn)行嗎？會(huì)正常運(yùn)行嗎？曾正常運(yùn)行過嗎？注釋代碼是我們應(yīng)該支持還是摒棄的呢？被注釋掉的代碼毫無用處，因?yàn)槊慨?dāng)開 發(fā)者讀到這些被注釋的代碼，總會(huì)冒出一些沒有答案的問題，它只會(huì)混淆開發(fā)者視聽，讓開發(fā)者分心而無法更好專注于有用的代碼。
對(duì)于提交被注釋掉的代碼這件事情，只有一個(gè)原則，那就是：
原文鏈接：http://dev.solita.fi/2013/07/04/whats-in-a-good-commit.html
譯文鏈接：http://kb.cnblogs.com/page/181762/http://kb.cnblogs.com/page/181762/
本文標(biāo)題：一次優(yōu)秀的代碼提交應(yīng)該包含什么?
本文鏈接：http://m.5511xx.com/article/cddscii.html
