Документируйте "зачем", а не "что".

Документируйте "зачем", а не "что".

Одно из частых замечаний, которое я оставляю при рецензировании кода (code review) это вариации на тему "вижу что здесь делается, но не вижу зачем". Статистику не собирал, но чуть ли не в каждом третьем по ощущениям. Представим C++ код вроде

...

// Sort the items container.

std::sort(items.begin(), items.end());

...

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

...

// Sort the data so that we can use binary search below.

std::sort(items.begin(), items.end());

...

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

Схожая ситуация - описания коммитов / pull requests, не сообщающие ничего нового по сравнению с кодом. Например, гипотетический коммит может включать в себя конфигурационный файл и изменять в нем параметр MemoryLimit с 32 мегабайт до 64. При этом описание коммита гласит: "Update MemoryLimit from 32 to 64 MiB". Как и выше, такая формулировка фактически дублирует то, что может быть легко понято и так, но скрывает назначение этого изменения. Как минимум была бы полезна ссылка на баг, который это изменение намеревается исправить. Но лучше кратко описать ожидаемый эффект прямо в тексте коммита - в будущей археологии кода это будет полезно.

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

Наверное, в чем-то это неудивительно - документировать то, что понятно и известно, проще. Описывать "зачем" сложнее - это подъем на уровень выше, формулировки на котором требуют соединения менее связных кусочков информации. Однако тем и ценнее эти усилия - именно во время этих упражнений можно выявить шероховатости и "пыльные углы" в системах и командах. Нередки случаи, когда при попытке документировать примеры для того или другого конфигурационного параметра оказывается, что никто не знает, зачем он вообще нужен. Или когда при вопросе о причине увеличения memory limit оказывается, что это лишь теория, что это может помочь и вглубь еще никто не копал. И прочее, и подобное.

В общем, в документации и комментариях зачем гораздо ценнее, чем что.