Как был предотвращён очередной виток эскалации арабо-еврейского конфликта.

Java — это, во многих отношениях, С++−−.

Michael Feldman.

Только что закончил совещание с представителем субподрядчика из Рамаллы. Тамошняя контора пишет интерфейс к нашему новому проекту. На Java. Это уже само по себе плохо («если бы в Java была настоящая сборка мусора, большинство программ удаляли бы сами себя при запуске» © Robert Sewell), но ведь они же ещё и документацию не предоставляют! В коде из комментариев — только заглушки, чтобы компилятор не ругался.

Стандартный тест на качество документации выглядит так: берём только документацию, выкидываем весь код, — благо, Doxygen это легко делает. Берём свежеиспечённого джуниора, ещё не отравленного реальной работой, только-только из вуза. Даём ему эту документацию, просим написать по документации программу. Если результат отличается от того, что у нас было изначально, в чём-то, кроме имён переменных, — значит, документация плохая, и её надо исправлять.

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

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

А потом, уже после совещания, я послал им следующую картинку:

( Всем утверждающим, что код — лучшая документация, посвящается: )