[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

3. Журналы изменений

Ведите журнал изменений для каждого каталога, описывающий изменения, вносимые в исходные файлы, которые расположены в этом каталоге. Целью этого является то, чтобы люди, которые в будущем будут искать ошибки, могли узнать об изменениях, которые привнесли эти ошибки. Зачастую, новая ошибка может быть найдена просмотром того, что было изменено в последнее время. Еще более важно то, что журнал изменений может помочь избежать концептуальной несогласованности между различными частями программы; он могут дать Вам историю того, как возникли конфликтующие концепции.

Следует использовать команду Emacs M-x add-change для того, чтобы добавить новую запись в журнал изменений. Запись должна начинаться с символа "звездочка", за которым следует имя измененного файла и, в скобках, имена измененных функций, переменных или чего-либо еще, после чего должен стоять символ "двоеточие". Далее поместите описание выполненных Вами изменений.

Несвязанные записи следует разделять пустыми строками. Когда две записи представляют собой части одного изменения, они должны находится вместе и между ними не должно быть пустых строк. В этом случае Вы можете опускать имя файла и символ "звездочка", если следующие друг за другом записи относятся к одному файлу.

Некоторые примеры:

 * register.el (insert-register): Return nil.   
 (jump-to-register): Likewise.   
   
 * sort.el (sort-subr): Return nil.   
   
 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):   
 Restart the tex shell if process is gone or stopped.   
 (tex-shell-running): New function.   
   
 * expr.c (store_one_arg): Round size up for move_block_to_reg.   
 (expand_call): Round up when emitting USE insns.   
 * stmt.c (assign_parms): Round size up for move_block_from_reg.   

Не нужно описывать полностью цель изменений или то, как они работают вместе. Лучше помещать такие объяснения в виде комментариев в коде. В журнале достаточно написать просто "New function", а комментарий, объясняющий что эта функция делает стоит поместить в исходный текст как комментарий.

Тем не менее, иногда полезно написать одной строкой объяснение цели большой группы изменений.

Журнал изменений объясняет, чем ранние версии программы отличаются от текущей версии. Интересующиеся люди могут увидеть текущую версию, и им не нужен журнал изменений для того, чтобы понять, что она из себя представляет. Однако журнал изменений должен давать четкие объяснения как изменялась программа по сравнению с более ранними версиями.

Когда Вы изменяете способ вызова функции некоторым достаточно простым образом, и это изменение потребовало модификации всех вызовов этой функции, нет необходимости вводить отдельную запись для каждого измененного вызова функции. Достаточно написать в записи для вызываемой функции "All callers changed".

В случае, если Вы изменяете только комментарий или строки документации, достаточно ввести запись для файла целиком, без указания имен функций, и написать просто "Doc fix.". Не нужно сохранять записи об изменениях в файлах документации, поскольку документация обычно не содержит таких ошибок, которые сложно обнаружить и исправить. Документация не содержит взаимосвязанных и взаимодействующих частей, поэтому для исправления ошибки в документации Вам обычно не нужно знать историю ее возникновения.

Партнёры:

Хостинг: