Золотые правила кодовой документации

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

Совершенно очевидно, что этот человек написал 1-2 приложения «Hello world», где это, очевидно, справедливо. Мой ответ на это  был:

Как бы вы записали эту бизнес-логику в код, чтобы вы могли жить без комментариев?

Биржевой ордер с кодом выравнивания типа 27 необходимо сгруппировать со всеми другими последующими ордерами с кодом типа 27 (тогда и только тогда, когда они имеют лот округления ниже 0,01), прежде чем фактически выгружать их в течение периода времени не более 35 секунд. (Вымышленный пример в реальном приложении).

Конечно. Код может сообщать «что» он делает. Но только комментарии могут сообщить, «почему» это делает! «Почему» — это более широкая истина, которая просто не может быть выражена в коде. Это включает в себя требования, чувства, опыт и т. Д. И т. Д.

Поэтому пришло время написать еще один поляризационный пост в блоге, который (надеюсь!) Приведет к более жарким дискуссиям! Это о:

Золотые правила кодовой документации

Хорошая документация добавляет  удобочитаемость ,  прозрачность ,  стабильность и надежность  вашему приложению и / или API. Но что такое хорошая документация? Каковы составляющие хорошей документации?

Код это документация

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

• Не знаю код (кто-то еще написал это)
• Нет времени читать код (это слишком сложно)
• Не хочу читать код (кто хочет читать  код Hibernate  или  Xerces, чтобы понять, что происходит ??)
• Нет доступа к коду (хотя они могут  декомпилировать его )

Для всех остальных код  является  документацией. Таким образом, очевидно, что код должен быть написан так, чтобы документировать его назначение. Так что не пишите умный код, пишите элегантный код. Вот хороший пример того, как не задокументировать «цель» (за исключением нескольких носителей языка Perl):

`$=`;$_=\%!;($_)=/(.)/;$==++$|;($.,$/,$,,$\,$",$;,$^,$#,$~,$*,$:,@%)=(
$!=~/(.)(.).(.)(.)(.)(.)..(.)(.)(.)..(.)......(.)/,$"),$=++;$.++;$.++;
$_++;$_++;($_,$\,$,)=($~.$"."$;$/$%[$?]$_$\$,$:$%[$?]",$"&$~,$#,);$,++
;$,++;$^|=$";`$_$\$,$/$:$;$~$*$%[$?]$.$~$*${#}$%[$?]$;$\$"$^$~$*.>&$=`

Взято с:
http://fwebde.com/programming/write-unreadable-code/

Видимо, это печатает «Просто еще один Perl-хакер». Я, конечно, не буду выполнять это на моей машине, хотя. Не вините меня за потерю данных 

API это документация

Хотя API все еще является кодом, именно эта часть кода доступна большинству других. Таким образом, должно быть:

• Очень простой
• Очень лаконично

Простота — король, конечно. Краткость, однако, не совсем то же самое. Все еще может быть  просто  использовать API, который не является  кратким . Я бы рассмотреть вопрос об использовании в Spring  J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource  простого . Вы настраиваете это, вы вводите это, сделано. Но название вряд ли указывает на лаконичность.

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

Хорошие правила дизайна (и, следовательно, документации) для достижения  краткости  следующие:

• Не позволяйте методам с более чем 3 аргументами попадать в ваш публичный API.
• Не позволяйте методам / типам с более чем 3 словами в именах попадать в ваш публичный API.

Лучше всего избегать вышеуказанного. Если вы не можете избежать таких методов, держите вещи в секрете. Эти методы не могут быть использованы повторно, поэтому их не стоит документировать в API.

API должен быть задокументирован словами

Как только код «просачивается» в общедоступный API, он должен быть задокументирован понятными для человека словами. Правда,  java.util.List.add ()  уже довольно  лаконичен . Он четко  сообщает о своих намерениях . Но как это ведет себя и  почему ? Выдержка из Javadoc:

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

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

Инструменты отслеживания документации

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

При внесении изменений в свой код не столь очевидным способом (поскольку у ваших заинтересованных сторон не столь очевидные требования) добавьте короткий комментарий в соответствующий раздел кода со ссылкой на идентификатор отслеживания:

// [#1296] FOR UPDATE is simulated in some dialects
// using ResultSet.CONCUR_UPDATABLE
if (forUpdate && 
    !asList(CUBRID, SQLSERVER).contains(context.getDialect())) {

Да, сам код уже объясняет, что следующий раздел выполняется только в запросах forUpdate и только для диалектов CUBRID и SQLSERVER. Но  почему ? Будущий разработчик с удовольствием прочитает все, что они могут найти о проблеме  № 1296 . Если это актуально, вы должны указать этот идентификатор билета в:

• Списки рассылки
• Исходный код
• API документация
• Комментарии контроля версий
• Вопросы переполнения стека
• Все виды других документов с возможностью поиска
• и т.п.

Контроль версий это документация

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

Итак, следуйте этому правилу: Является ли изменение нетривиальным (фиксированное написание, фиксированный отступ, переименованная локальная переменная и т. Д.)? Затем создайте заявку и задокументируйте это изменение с идентификатором заявки в вашем коммите. Создание и ссылка на этот билет стоит вам всего 1 минуту, но это сэкономит будущему сотруднику часы исследования!

Нумерация версий — документация

Простая и краткая  версия система нумерации поможет пользователям понять, какую версию они должны обновить. Хорошим примером того, как сделать это правильно, является  семантическое управление версиями . Золотые правила здесь должны использовать  [X].[Y].[Z] схему управления версиями, которая может быть кратко изложена следующим образом:

/**
 * Returns the id
 *
 * @return The id
 */
public int getId() {
    return id;
}

// Check if we still have work
if (!jobs.isEmpty()) {

    // Get the next job for execution
    Job job = jobs.pollFirst();

    // ... and execute it
    job.execute();
}

if (!jobs.isEmpty()) {
    Job job = jobs.pollFirst();
    job.execute();
}