19.2.1.6. Сопровождайте заплаты документацией

19.2.1.6. Сопровождайте заплаты документацией

Данный момент очень важен. Если заплата вносит заметные пользователям дополнения или изменяет функции программы, то необходимо включить данные изменения в соответствующие man-страницы и другие файлы документации к заплате. Не следует полагать, что получатель будет счастлив документировать чужой код или использовать недокументированные функции в своем коде.

Документирование изменений хорошо демонстрирует некоторые полезные качества. Во-первых, это вежливо по отношению к человеку, которого вы пытаетесь убедить. Во-вторых, это демонстрирует ваше понимание того, что смысл внесенного изменения достаточно важен для того, чтобы объяснять его тем, кто не видит код. В-третьих, это демонстрирует заботу о людях, которые, в конце концов, будут использовать данную программу.

Хорошая документация обычно является наиболее заметным признаком, который позволяет отличить солидный вклад от быстрой и неаккуратной работы. Если созданию документации уделить необходимое время и внимание, то вскоре обнаружится, что пройдено 85% пути к принятию заплаты большинством разработчиков.

Поделитесь на страничке

Следующая глава >

Похожие главы из других книг

19.2.1.1. Отправляйте заплаты, а не целые архивы или файлы

Из книги Искусство программирования для Unix автора Реймонд Эрик Стивен

19.2.1.1. Отправляйте заплаты, а не целые архивы или файлы Если изменения включают в себя новый файл, который отсутствует в коде, то, естественно, приходится отправлять данный файл целиком. Однако если изменяются только уже существующие файлы, отправлять их полностью не


19.2.1.3. Не следует включать заплаты для генерируемых файлов

Из книги Эффективное использование STL автора Мейерс Скотт

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


19.2.1.6. Сопровождайте заплаты документацией

Из книги Искусство программирования для Unix автора Реймонд Эрик Стивен

19.2.1.6. Сопровождайте заплаты документацией Данный момент очень важен. Если заплата вносит заметные пользователям дополнения или изменяет функции программы, то необходимо включить данные изменения в соответствующие man-страницы и другие файлы документации к заплате. Не


19.2.1.7. Сопровождайте заплату пояснениями

Из книги Удвоение продаж в интернет-магазине автора Парабеллум Андрей Алексеевич

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


Совет 32. Сопровождайте вызовы remove-подобных алгоритмов вызовом erase

Из книги Разработка ядра Linux автора Лав Роберт

Совет 32. Сопровождайте вызовы remove-подобных алгоритмов вызовом erase Начнем с краткого обзора remove, поскольку этот алгоритм вызывает больше всего недоразумений в STL. Прежде всего необходимо рассеять все сомнения относительно того, что делает алгоритм remove, а также почему и как


19.2.1.1. Отправляйте заплаты, а не целые архивы или файлы

Из книги автора

19.2.1.1. Отправляйте заплаты, а не целые архивы или файлы Если изменения включают в себя новый файл, который отсутствует в коде, то, естественно, приходится отправлять данный файл целиком. Однако если изменяются только уже существующие файлы, отправлять их полностью не


19.2.1.3. Не следует включать заплаты для генерируемых файлов

Из книги автора

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


19.2.1.7. Сопровождайте заплату пояснениями

Из книги автора

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


Сопровождайте поля форм пояснениями

Из книги автора

Сопровождайте поля форм пояснениями Часто пользователи не могут совершить покупку, даже если очень хотят это сделать, так как не понимают, что нужно писать в том или ином поле. Размещайте описания-подсказки рядом с каждым полем, даже если вам его назначение кажется


Глава 20 Заплаты, разработка и сообщество

Из книги автора

Глава 20 Заплаты, разработка и сообщество Одно из самых больших преимуществ операционной системы Linux — это связанное с ней большое сообщество пользователей и разработчиков. Сообщество предоставляет множество глаз для проверки кода и множество пользователей для