標準更改註釋

我正在尋找一些方向來評論PHP中的更改的標準格式。在與大型項目的各種開發人員一起工作的過程中，評論一直處於瘋狂狀態，在大多數情況下，更改要麼評論不好，要麼根本沒有評論。標準更改註釋

下面是一個例子，請隨時就可以擴大：

 
/** 
* Author: [first and last name] 
* Date Changed: [YYYY-MM-DD] 
* Description: [description] 
*/

問：有誰知道在評論PHP變化的一種標準化的方式？

來源

2009-12-11 Torez

你使用任何種類的源代碼管理軟件嗎？這將自動讓作者和日期發生變化。根據SCM，您可能會掛鉤到提交操作並要求該人員添加描述更改的註釋。 – 2009-12-11 20:27:09

這樣的東西不應該被置於文件註釋。使用revision control software來存儲您的文件的所有版本（不只是最新的）。如果沒有它，絕不允許開發人員工作這種軟件可以讓你做更的源代碼：

你可以找到誰改變了文件的每一行
您可以還原文件到以前的（或工作）版本
您可以創建源的不同分支，並自動將它們合併
您可以自動化軟件的建設，並自動運行測試
備份源存儲庫，你永遠不會失去你的工作
... and more

來源

2009-12-11 20:31:58

+1。這種元數據（誰做了什麼，什麼時候做）應該由版本控制管理，而不是評論。對於試圖理解代碼的人或使用文檔，應該使用評論來提供有用的信息。 – Jeff 2009-12-11 20:57:32

除了使用源代碼控制，意見一般應側重於對源代碼的當前狀態，不能提供詳細詢問病史，除非是爲了說明的內容。

註釋應該描述一個程序的如何和爲什麼並不會是一個行政暫存器或歷史填寫表單。一個工程師如何與另一位工程師進行交流 - 或者提醒自己 - 這個概念模型是什麼。這可以解釋實施的基礎，如其理念，預期用法或世界觀。但是，正如你所知道的那樣，工程師不能依賴做文員。

我想我們都看到來源是這樣的：

/* 
* Function: (fill in name) 
* 
* Returns: (fill in type) 
* 
* Date: (current date) 
* 
* Revision (revision number) 
* 
* Author: (your name or initials) 
* 
* Description: 
* (describe function) 
*/

那裏沒有一個人填寫任何但是最無用的細節，如果在所有。

來源

2009-12-11 20:51:22 wallyk

標準更改註釋

回答

相關問題