Комментарии 15
А чего вы себе такие "никакие" cons документации выбрали? А что насчет "документация даже в коде требует поддержки", "неактуальная документация хуже ее отсутствия", "не все можно запихнуть в текст" и "90% документации реально никогда никому не нужно"?
«документация даже в коде требует поддержки»
Что значит даже? Любая документация несет за собой ответственность за ее поддержку, это очевидно. Независимо от того, в коде это документация, или вне.
«не все можно запихнуть в текст»
Пишите свой код так, чтобы текст комментариев не пришлось никуда «запихивать». Большую часть информации о коде должен предоставлять сам код.
90% документации реально никогда никому не нужно
От куда такая цифра? Проводились какие-то иследования?
Поддерживает кто эту документацию или нет - это уже вопрос к тому, нужна ли такая тема, а не как ее решать. Если всем будет удобно и эта документация централизована, то зачем другим использовать что то другое, если им всеравно прийдется "тут" читать. Эти документы не надо редактировать, их надо создавать новые при изменении. Это документы не того глубокого (до дублирования) технического содержимого и они не так часто меняются. Актуален тот, соответственно, у которого дата более последняя. Как то так.
Прочитал и всё так же думаю, код должен сам себя документировать, дажеЕслиЭтоПеременнаяИзДесятиСлов.
Документация должна ограничиваться описанием методов, параметров, эксшепшенов и т.п. Т.е. документация для автокомплита ИДЕ.
Проблема заключается в том, что всё очень индивидуально. Что одному очевидно, другому не понятно.
Сложные вещи, которые не читаются - надо рефакторить, чтоб читались.
За всё время работы встретил только одного человека, кто не мог прочитать мой код. Он жаловался что нет документации и код не понятный.
Всё встало на свои места, когда я его код увидел, он был усыпан документацией и выглядел так
if (request()->code):
// helper
$fbh = $fb->getRedirectLoginHelper();
if (isset(request()->state)): $fbh->getPersistentDataHandler()->set('state', request()->state); endif;
try {
// get token
$at = $fbh->getAccessToken();
request()->session()->put('ap_fb_auth_token', $at);
// redirect
return redirect()->route('directory.facebookpage', ['dtoken' => $dtoken, 'btoken' => $btoken]);
} catch(\Facebook\Exceptions\FacebookResponseException $e) {
// error
request()->session()->flash('flash_error', ['There was an issue. Please try again.']);
return redirect()->route('directory.facebook', ['dtoken' => $dtoken, 'btoken' => $btoken]);
} catch(\Facebook\Exceptions\FacebookSDKException $e) {
// error
request()->session()->flash('flash_error', ['There was an issue. Please try again.']);
return redirect()->route('directory.facebook', ['dtoken' => $dtoken, 'btoken' => $btoken]);
}
else:Документация должна ограничиваться описанием методов, параметров, эксшепшенов и т.п. Т.е. документация для автокомплита ИДЕ
Это один из тезисов, который я несу на протяжении всей статьи.
Проблема заключается в том, что всё очень индивидуально. Что одному очевидно, другому не понятно
Я согласен. Но ведь команда на то и команда — в ней должно быть как можно больше понимания и взаимодействия внутри. Нужно писать документацию так, чтобы понятно было всем. Для этого нужны обсуждения с коллегами (о чем я упомянул).
Всё встало на свои места, когда я его код увидел, он был усыпан документацией и выглядел так
В вашем примере я не вижу ни капли документации. Я вижу одни комментарии, которые создают шум (об этом я кстати тоже упомянул).
Вопрос гниения документации не раскрыт. Вопрос документации за пределами кода (например, схема взаимодействия компонент и т.д.) не раскрыт.
Для меня было открытием после прочтения книги «Чистый код» Роберта Мартина что документация в коде по большому счету и не нужна. Если код чист и с внятным неймингом.
Купил несколько экземпляров книги и стал раздавать коллегам.
В этом смысле, Хабр мог бы составить конкуренцию КодеПроджекту, но здесь пока нет возможности прикреплять свои файлы, разве что ссылаться на внешние источники, допустим, тот же Гитхаб. Да и с сортировкой статей по тематике тоже не все идеально.
Как вариант статьи можно писать на собственных сайтах, у меня это, например, emery-emerald.narod.ru и erfaren.narod.ru. Но тоже, статьи там все древние. Кроме того, в принципе, можно публиковать свои статьи на sql.ru. Для примера, моя статья «Программа сбора данных от нескольких клавиатурных устройств для учета рабочего времени» опубликована там в www.sql.ru/forum/830155/programma-sbora-dannyh-ot-neskolkih-klaviaturnyh-ustroystv-dlya-ucheta-rabochego-vremeni. По ней мы до сих пор ведем учет рабочего времени на предприятии в собственной конфигурации 1С.
А читать документацию у нас не очень любят, разве что, когда приспичит. Но даже в этом случае, сначала ищешь подходящие статьи на тему и только, если таковых нет, штудируешь документацию, а, чаще всего, код. Вот ситуацию из жизни. Я предпочитаю ныне использовать C++ / WTL. По WTL документация есть, но слабенькая, статьи тоже есть, но, так себе. Что-то серьезное можно выяснить, только изучая непосредственно код. Хотя, чем больше узнаешь, тем больше скатываешься на уровень WinAPI.
Поэтому, проявите оригинальность. Уговорите своих коллег писать и публиковать статьи, хотя бы своей корпоративной сети. Добавьте им плюшек за это, организуйте интересные конкурсы. Зато, если что забыл или не понял, почитал соответствующие авторские статьи и все чики-пики. А, читать и писать документацию в стиле Doxygen, это, как по мне, садо-мазо :).
Опыт ~15 лет практики привёл меня к вот таким соображениям:
Implementation is documentation.
Нужен документ с общим описанием логики работы важных частей на высоком уровне (желательно со схемами, а не просто текст).
Комментарии в коде - только в тех местах, где могут быть явные затруднения в понимании логики работы через анализ кода.
Т.е. документация нужна, но её должен быть необходимый минимум, иначе затраты на её поддержку не будут окупаться.
Документирование кодовой базы. Зачем и как?