代碼提交的註釋的最佳實踐

您使用什麼模板來提交代碼註釋？模板的代碼提交的註釋的最佳實踐

一個例子是：

（變化1）：（源文件1.1，1.2）：（由變化的細節），（爲什麼）
（變化2）：（源（爲什麼）

理想情況下，每個更改應映射到問題跟蹤器中的問題。這個模板好嗎？

來源

2009-04-16 amit_grepclub

這裏是我的想法......這些都將根據您具體的開發方法是開放的解釋。

你應該經常提交，每次提交都需要一個焦點，所以在此基礎上，評論應該簡短並且詳細說明提交的重點是什麼。
我張貼在您的評論的什麼，與爲什麼和如何被其他地方詳述（最好在你的bug跟蹤）的粉絲。爲什麼應該是票證，並且在關閉票證後，您應該對該特定問題的解決方式有一些說明。
如果沒有以其他方式處理（例如TRAC/SVN交互），那麼對您的錯誤跟蹤系統的引用是很好的。這樣做的原因是，如果他們正在尋找更多關於提交的信息，那麼其他開發人員就會朝着正確的方向發展。
不要包含特定的文件名，除非修復程序非常複雜且需要詳細信息。即使如此，複雜的細節可能屬於錯誤跟蹤您的實現註釋，而不是版本控制。編輯好的文件，差異細節等應該包含在版本控制中，我們不希望花時間重複這些。

鑑於這些想法，一個例子提交評論對我來說會是這樣的

Req3845：更新驗證使用在Req3831開發新的正則表達式驗證。

簡而言之，溝通了發生了什麼變化，併爲他人提供某種參考，以獲得更多信息而不會讓你失望。

來源

2009-04-16 06:12:52 jcelgin

特別贊同最後一點...不要在提交註釋中列出文件名，除非您的版本控制不允許您在事後推斷受影響的文件。考慮到這些評論有時候可能被看作是一個大集合集合的一部分。 – 2009-04-16 07:06:55

請記住，如果有人需要更改內容的細節，他們可以得到差異。也就是說，我通常爲每一個重大改變都寫一兩句話，然後在最後修正一些小的修正。

來源

2009-04-16 06:03:42 rlbond

「我平時寫一兩句話對每個重大變化」約/含...什麼？ – 2011-06-23 14:24:03

我嘗試將我的修復保留在單獨的簽入中。

我不使用實際的模板，而是一個精神模板，就像這樣。

問題 - dev級別的摘要問題。

問題跟蹤器具有所有管理細節，並且可以查看代碼更改的更改/差異，因此評論是爲了瞭解dev爲什麼/什麼問題。

來源

2009-04-16 06:09:54

我儘量遵循相同的規則作爲代碼註釋：

解釋爲什麼，而不是HOW。

IMO評論應包含對問題的引用（任務跟蹤器或需求）。哪些文件受到影響已經可以從版本控制系統獲得。除此之外，它應該儘可能短，但仍然可讀。

來源

2009-04-16 06:10:27 Treb

如果您使用錯誤跟蹤系統，請包含相關的故障單號碼。

您不需要提及已更改的文件或您的姓名。源代碼庫可以自行計算出來。描述這些變化只有在diff不是非常明顯的情況下才有意義。

確保你有一個良好的第一線，因爲這頻頻出現在變化歷史來看，人們需要找到這個東西（bug跟蹤票號應該去那裏，例如）。

嘗試提交在一個單一的變更相關的變更（和分裂無關變爲兩次提交，即使對同一文件）。

來源

2009-04-16 06:12:05 Thilo

作爲簡單的英語沒有硬性規定。我嘗試用最少的話來解釋所做的工作。任何尋找變化歷史的人只是想知道在某個特定變化中發生了什麼。如果有人在更多的細節之後，那麼在代碼中。

我遵循的第二件事是，如果有任何相關的錯誤，然後堅持，或者如果它與任何開發任務相關，然後將其與該變化相關聯。

來源

2009-04-16 06:22:19

這是我見過的成功使用：

參考錯誤號碼或功能ID
變化的簡要說明。什麼改變了。
代碼審查者（以確保你有一個），除非由簽入系統處理。
測試儀或說明的名稱，其中測試運行（如果在後期的過程中，你正在格外小心）

來源

2009-04-16 07:41:15

我用Chaosben在JEDI Windows API blog介紹的簡單方法。

爲了得到一個資源庫做的變化的快速視圖，我們建議寫簡短精練評論開始每行一個這些字符的：

+如果您添加了功能/功能/ ...

-如果您刪除了功能/功能/ bug/...

＃，如果你改變了什麼

這樣做，這樣，其他開發者可以找到所需的修訂要好得多。

來源

2009-04-16 17:51:41 stukelly

我在每個段落前加上+ - *或！

+ means its a new feature 
- means feature is removed 
* means feature is changed 
! means bugfix

我不認爲你應該提交什麼部分代碼被改變的詳細說明，因爲這就是爲什麼每一個VC有差異:)

來源

2009-04-16 17:58:37 majkinetor

如果兩個文件改變爲不同的原因，他們應該在不同的提交中一次只能提交一個以上的代碼文件是因爲它們都屬於同一個修訂/更改

來源

2009-04-16 18:26:31

首先，提交應解決單個問題（單獨提交邏輯上單獨的更改）。如果您不知道在提交消息中寫什麼，或者comit消息太長，這可能意味着您在提交中有多個獨立的更改，並且應該將其分成更小的項目。

我認爲提交預期和由GIT中使用的消息約定使得多大意義：

提交消息的第一行應是一個簡短的說明
如果合適，前綴上面總結行中提及的子系統前綴，例如「文檔」或「的contrib：」
在接下來的段落或段落描述的變化，解釋了爲什麼是怎樣的

來源

2009-04-17 14:31:16

代碼提交的註釋的最佳實踐

回答

相關問題