Стандартные изменения

Question

Я ищу какое-то направление в отношении стандартного формата для комментариев к изменениям в PHP. Постоянно работая с ассортиментом разработчиков по крупномасштабным проектам, комментарии работают безупречно, и в большинстве случаев изменения либо плохо комментируются, либо вообще не комментируются.

Вот пример, пожалуйста, расширить на нем:

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

Q: Кто-нибудь знает стандартизированным способом комментирования изменений в PHP?

Answer 1

Такие вещи не следует размещать в файлах комментариев. Используйте revision control software, чтобы сохранить все версии вашего файла (а не только самые последние). Никогда не разрешайте разработчикам работать без него. Такое программное обеспечение позволяет сделать гораздо более с исходным кодом:

• Вы можете найти, кто изменил каждую строку файла
• Вы можете вернуть файл к предыдущим (или рабочему) версии
• Вы можете создать различные ветви источника и объединить их автоматически
• вы можете автоматизировать построение вашего программного обеспечения и запуск тестов автоматически
• Резервное копирование хранилища источник, и вы никогда не будете потеряли работу
• ... and more

Answer 2

Помимо использования системы управления версиями, комментарии, как правило, должны быть сосредоточены на текущее состояние исходного кода, а не предоставлять подробную историю, за исключением, возможно пояснительную контекста.

Комментарии должны описывать хау и почему программы и не являются административным блокнотным или историческим заполнение формы. Как один инженер общается с другим инженером или, может быть, напоминает себе, что такое концептуальная модель. Это может объяснить основу для реализации, такую ​​как ее философия, ожидаемое использование или мировоззрение. Но, как вы знаете, инженеры не могут считаться клерками.

Я думаю, что мы все видели, как это источник:

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

, где никто не заполнил любой, но наиболее бесполезных деталей, если на всех.