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

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

Такие пакеты, как Pydoc для Python и Javadoc для Java, помогают автоматизировать часть процесса. Инструмент Godoc делает то же самое для Go.

Что такое Годок?

Godoc — это пакет Go, который позволяет создавать, управлять и использовать документацию Go «в стиле Go». Путь Go — это набор принципов, которым вы, как программист Go, должны следовать, чтобы улучшить качество кода.

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

instagram viewer

Годок похож на Javadoc, документатор кода для Java. Они оба используют комментарии и код в модулях для создания документации. И оба инструмента структурируют эту документацию в HTML, чтобы вы могли просматривать ее в браузере.

Начало работы с Годоком

Пользоваться Годоком легко. Для начала установите пакет Godoc с веб-сайта golang с помощью этой команды:

идти получить golang.org/x/tools/cmd/godoc

Выполнение этой команды установит Godoc в указанной вами рабочей области. После его завершения вы сможете запустить Годок команду в терминале. Если при установке возникли какие-либо ошибки, попробуйте обновить Go до последней версии.

Godoc ищет однострочные и многострочные комментарии для включения в создаваемую им документацию.

Обязательно отформатируйте код в стиле Go, как описано в публикация «Эффективное го» командой Go для достижения наилучших результатов.

Вот пример использования однострочных комментариев в стиле C++:

// User — это структурная модель, содержащая
тип Пользователь структура {
}

Вы также можете использовать блочные комментарии в стиле C:

/* 
Пользователь - это пользовательская структура данных
Вы можете включить сюда любой текст, и сервер Godoc отформатирует его при запуске.
*/
тип Пользователь структура {
}

В комментариях выше «Пользователь» начинает предложения, потому что комментарий описывает, что делает структура «Пользователь». Это одна из многих тем, которые обсуждает Go way. Очень важно начинать предложения документации с полезного имени, поскольку первое предложение появляется в списке пакетов.

Запуск сервера Godoc

После того, как вы прокомментировали свой код, вы можете запустить Годок в вашем терминале, из каталога кода вашего проекта.

Обычно разработчики Go используют порт 6060 для размещения документации. Это команда для запуска сервера Godoc на этом порту:

годок-http=:6060

Приведенная выше команда размещает документацию по вашему коду на локальный или 127.0.0.1. Порт не обязательно 6060; godoc будет работать на любом незанятом порту. Однако всегда лучше следовать соглашениям документации Go.

После запуска команды вы можете просмотреть документацию в браузере, посетив локальный: 6060. Время, необходимое Godoc для создания вашей документации, будет зависеть от ее размера и сложности.

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

// имя пакета
упаковка пользователь
// fmt отвечает за форматирование
импорт (
 "ФМТ"
)


// Пользователь - это структура человеческих данных
тип Пользователь структура {
 Возраст инт
 Имя нить
}


функцияглавный() {
// человек — это инициализация структуры User
 человек := Пользователь {
 Возраст: 0,
 Имя: "человек",
 }


ФМТ. Println (чел. Разговаривать())
}
// Talk — это метод структуры User
функция(Пользователь-получатель)Разговаривать()нить {
возвращаться «Каждый пользователь может что-то сказать!»
}

Если вы запустите Godoc в приведенном выше модуле кода, вы должны увидеть что-то вроде этого:

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

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

Индекс содержит ссылки на объявления типов и методы, чтобы вы могли быстро перейти к ним.

Godoc также предоставляет функциональные возможности для просмотра исходного кода, из которого состоит пакет, в Пакетные файлы раздел.

Улучшение вашей документации с помощью Godoc

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

Если вы хотите сделать ссылку на ресурс, напишите URL-адрес в своем комментарии, и Godoc распознает его и добавит ссылку. Для абзацев оставьте пустую строку комментария.

// Основной пакет
упаковка главный
// Документ представляет собой обычный документ.
//
// Ссылка на https://google.com
тип Документ структура {
 страницы инт
 использованная литература нить
 подписал логический
}


// Write записывает новый документ в хранилище
//
// Вы можете узнать о писательстве на сайте Wikipedia.com
функцияНапишите() {
}

Обратите внимание, что Godoc требует, чтобы вы написали URL-адреса полностью, чтобы связать их. В этом примере URL-адрес Google включает в себя https:// префикс, поэтому Godoc добавляет ссылку на него. Поскольку домен Википедии сам по себе не является полным URL-адресом, Godoc оставит его в покое.

Вот несколько лучших принципов, которые следует применять при документировании кода Go:

  • Сохраняйте документацию простой и лаконичной.
  • Начните предложение функций, типов и объявлений переменных с их имен.
  • Начните строку с отступа, чтобы предварительно отформатировать ее как код.
  • Комментарии, начинающиеся с «ОШИБКА (имя)» типа «ОШИБКА (Джо): Это не работает», являются особыми. Godoc распознает их как ошибки и сообщит о них в своем собственном разделе документации.

Godoc может облегчить ваши проблемы с документацией

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

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

Ознакомьтесь с документацией по пакету Godoc, чтобы узнать больше об использовании Godoc.