Автор Кэрри Ма
Вы когда-нибудь работали над проектом, отдыхали и возвращались, спрашивая себя: «А где я был ?!» Чаще всего разработчики работают со сложными алгоритмами, архитектурами и функциями, которые требуют дополнительного объяснения кода.
Чтобы быть хорошим разработчиком, нужно обладать некоторыми хорошо известными качествами, в том числе умением решать проблемы, внимательным логиком и любопытным творчеством. Быть отличным разработчиком также означает умение сотрудничать и общаться. Разработка программного обеспечения часто включает планирование архитектуры и понимание технических решений. При завершении или передаче программного обеспечения часто бывает полезно предоставить дополнительные комментарии, документацию и информацию о коде.
(Отказ от ответственности: этот совет посвящен документированию исходного кода. Если вы ищете совет по документации API, прочтите блоги экспертов Taylor Singletary, Kristen Womack и Chris Chinchilla.)
Написание хорошего кода
Прежде чем описывать свой код, вам действительно нужно написать хороший код. Следуя совету Амита Шекхара, хороший код должен быть:
- Читабельный: тот, кто никогда не видел ваш код, должен понять его.
- Понятно: все названия хорошо описаны и нет ничего двусмысленного.
- Ремонтопригодность: код разбит на части, где все имеет четкую цель, и в него легко добавлять или изменять функции.
- Возможность повторного использования: код создается как платформа, в которой другие могут повторно использовать фрагменты кода.
- Эффективно: алгоритмы разработаны для быстрого выполнения задач.
Зачем документировать?
Итак, когда код хорошо написан и не требует пояснений, зачем нужна документация и комментарии? Чтобы не тратить время зря, не документируйте, если:
- Код написан плохо или разовая задача
- Вы пишете о каждом решении в каждой строке, так как это затрудняет чтение кода.
- Вы описываете, что делает код, поскольку это должно быть самоочевидным
- Решения еще не приняты, и его нужно будет изменить.
Документация полезна и стоит усилий, когда:
- У вас несколько соавторов, и вы хотите, чтобы люди были на одной странице
- У вас сложный код, который не является тривиальным, поэтому необходимы дополнительные объяснения, чтобы объяснить «почему»
- Вы хотите сэкономить разработчикам время, которое потребуется на анализ кода, и вместо этого дать им возможность быстро изучить хорошо написанную документацию.
- Вы будете пересматривать код через несколько месяцев и, скорее всего, к тому времени забудете подробности.
- Вы хотите, чтобы люди правильно использовали ваш код, поэтому хотите убедиться, что вы описываете, как он работает, формат и как другие могут его лучше всего использовать.
Для получения дополнительной информации прочтите объяснение Тома Даллинга почему встроенные комментарии - это вообще плохая идея, Руководство по написанию документации Write the Docs и список Ирмы Азарян, почему документация важна.
Написание хорошей документации
Как разработчик, вы можете не думать о себе как о техническом писателе, но способность описывать код на самом деле улучшает ваши навыки - точно так же, как способность преобразовывать сложные предметы в понятные термины делает вас лучшим коммуникатором и учителем.
Часто с проектами ожидается README, поскольку он дает общий обзор того, как использовать код. Документацию часто читают разные группы: пользователи, которые хотят использовать ваш код и запускать программу, и разработчики, которые хотят изменить или внести свой вклад в ваш код. Помня об этом, важно указать следующие детали:
- О чем ваш проект и что он решает
- Контактная информация или как получить поддержку
- Инструкции по установке и настройке
- Лицензирование проекта
- Как люди могут внести свой вклад и каким стандартам следовать
- Фрагменты кода и примеры
Чтобы найти отличные шаблоны README, ознакомьтесь с шаблоном PurpleBooth и руководством Калеба Томпсона.
Советы по комментированию см. В советах Джейка Рошело по стилизации комментариев в исходном коде и в анализе Билла Сурура о добавлении комментариев в код. Обычно вы хотите:
- Отформатируйте стиль комментариев в удобочитаемой и удобной форме
- Опишите, почему вы поступили не так, как ожидалось
- Описывать сложные алгоритмы, методы и функции
- Опишите любые ошибки или обходные пути, которые вы не можете контролировать (например, когда вы используете чужой фреймворк, библиотеку или код)
С этим советом, я надеюсь, вы лучше подготовитесь к комментированию, документированию и, как правило, к тому, чтобы немного успокоить вас и свою команду разработчиков!
Мы спрашиваем сообщества #tech, #womeintech и #womeninbusiness: Насколько ценны для вас технические блоги Chic Geek? Напишите нам в Твиттере Chic Geek YYC с предложениями!
Посетите нас по адресу:
