Правила хорошего тона при поддержке собственных модулей

Форматирование кода и gofmt §

Код, написанный в одном стиле, удобно и приятно читать. Сравните сами:

Плохо отформатированный код:

func Add(a, b ArrInt) ArrInt 
 
{
length := len(a)
if length-len(b) > 0 
    {
length = len(b) }
c := make(ArrInt, length)
 
for i := 0; i <length; i++ 
    {
    c[i]=a[i]+b[i]
    }
 
    return c } 

Хорошо отформатированный код:

func Add(a, b ArrInt) ArrInt {
    length := len(a)
    if length-len(b) > 0 {
        length = len(b)
    }
    c := make(ArrInt, length)
    for i := 0; i < length; i++ {
        c[i] = a[i] + b[i]
    }
    return c
} 

В разных языках вопрос с форматированием решается по-разному. Например, в Python есть официальный стандарт PEP 8, а в C++ — несколько популярных стилей.

Note

Go решает этот вопрос необычным образом: весь код должен быть отформатирован стандартной утилитой gofmt или её расширенной версией goimports. Утилита goimports делает то же самое, что и gofmt, но ещё автоматически оптимизирует и сортирует импорты.

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

Форматирование — далеко не единственное, что определяет качество кода. Разработчики по невнимательности могут употреблять конструкции вроде a = append(a,) или fmt.Printf("Here must be number %d"). В этом случае могут помочь линтеры.

Линтеры и go vet §

В экосистеме Go наиболее распространённый линтер — vet.

В отличие от форматера кода gofmt, линтер не даёт стопроцентной гарантии правильности своей работы — могут быть ложноположительные и ложноотрицательные срабатывания. Скорее всего, придётся немного поколдовать с настройками, прежде чем линтер начнёт корректно работать в каждом проекте. Манипуляции с настройкой и подключением линтера к системам CI/CD окупят себя, когда вы сэкономите время на этапе код-ревью.

Документация и godoc §

В экосистеме Go есть стандартная утилита для создания документации на основе комментариев в коде — это godoc. Запустите go install golang.org/x/tools/...@latest, чтобы установить все пакеты и утилиты golang.org/x/tools, в том числе godoc.

Документация к любой сущности (функции, структуре, переменной или пакету) — это комментарий, который предшествует декларации этой сущности. Например:

// Foo выполняет очень важную роль в проекте — ничего не делает :)
func Foo() {}
 
// описывает новый тип данных «никнейм» на основе стандартного строкового типа
type nickname string 

На основе таких комментариев godoc может сгенерировать документацию в формате HTML, man pages и т. д.

Документирование публичного API разрабатываемых пакетов позволяет сторонним разработчикам получить ответы на вопросы относительно функционала без чтения исходников. Документируйте свои пакеты — и жизнь пользователей станет лучше.

Тестирование кода §

Как известно, код без тестов по определению сломан. Поэтому тестирование кода — обязательная часть разработки.

---

📂 Go | Последнее изменение: 23.08.2024 09:47