Что менее раздражает: нет документации исходного кода или плохой документации по коду?

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

Я сказал ему, что в этом случае он никогда не должен был комментировать, только после того, как действительно проверил, что там происходит, потому что кто-то, кто прочитает его мнение как действительное выражение, не проверит сам и не испортит. Он мог бы добавить: "Это предположение, пожалуйста, проверьте сами". но он этого не сделал. Даже если комментариев не было, было бы лучше, потому что разработчик должен проверить себя.

Лично я очень строг в документации по коду. Это не значит, что я прокомментирую каждую строку кода, но сводки методов, классов и т.д. Являются обязательными, а дополнительные строки для сложных частей кода тоже помогают.

Я должен добавить, что я работаю в команде из 10 разработчиков, где никто не пишет код только для себя. Расходы меньше времени на документацию кода означает, что другие разработчики тратят больше времени, чтобы получить смысл кода.

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

Как вы думаете? Вам все равно, или вы тоже видите это в своей повседневной работе? Что еще хуже для вас: нет документации по коду или документации плохого кода?

Спасибо!

Майкл

ОТВЕТЫ

Ответ 1

Неправильная документация, которая выглядит авторитетной, хуже документации.

Неполная документация лучше, чем никакая документация.

Спекулятивная документация, помеченная как таковая, часто лучше, чем никакая документация.

Ответ 2

"Документация похожа на секс, когда это хорошо, это очень, очень хорошо, и когда это плохо, это лучше, чем ничего. (Дик Брэндон)"

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

Ответ 3

Я считаю, что качество кода значительно больше влияет на мою способность работать над ним, чем на качество документации.

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

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

Ответ 4

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

Если это помогает кому-то, кто раньше проработал код, он может дать вам голову.

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

Я вижу, что многие люди говорят плохой документации хуже, но не могут придумать один сценарий (и я его никогда не видел), где это было действительно хуже.

Обычно вы слышите критики против документации от людей, которые действительно не понимают, что делает их собственный код, и не могут поэтому должным образом прокомментировать его. (IE:, они являются авторами сценария плохого кода/комментария, обсуждаемого в настоящее время)

Ответ 5

Документация не намного лучше. Я бы предпочел понять это сам, чем ввести неверное руководство.

Ответ 6

Нет документации. Меня укусили вводящие в заблуждение документы и смирились с тем, что я цинично отношусь к тому, что он утверждает. В большинстве случаев его обычно то, что разработчик хотел сделать, а не то, что он делает (особенно в отсутствие теста:/)

Ответ 7

Неверная документация хуже документации.

Ответ 8

Если разработчики (т.е. пользователи API) имеют доступ к исходному коду, то плохая документация хуже, чем никакой документации. Но по крайней мере, как только пользователи выяснили, что документация плохая, они могут посмотреть исходный код, чтобы узнать ответы на свои проблемы.

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

Ответ 9

Это, очевидно, переходит в субъективную территорию, но, основываясь на моем определении плохой документации, это намного хуже, чем отсутствие документации!

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

Она вообще не ленилась. С каждым исходным файлом реализации она написала руководство (описываемое как таковое с оглавлением и всем). Каждый из них составлял не менее дюжины страниц, а иногда и до 30 страниц. Это руководство почти полностью касалось того, как был реализован код и часто был даже длиннее самого кода (обычно для чтения и понимания кода, чем для руководства, требуется меньше времени). Это было также совершенно скучно, описывая детали, которые обычно были бы очевидны, например, как используются переменные и т.д.

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

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

Ответ 10

IF у вас есть хороший код, тогда вам вообще не нужна документация. "GoodCode" Я имею в виду, что каждая функция имеет самоочевидное имя, назначение функции ясное и т.д.

Единственное, что нужно прокомментировать, это ОЧЕНЬ ОПТИМИЗИРОВАННЫЕ методы, которые читабельность пожертвовала с целью оптимизации. Но это должно быть не более 3-5 функций для каждого приложения: обычно только 20% приложений вызывает проблемы с производительностью (или любые другие проблемы). И только оптимизация 20% этих 20% (всего 4% всей заявки) может быть плодотворной для оптимизации.

Чем меньше комментариев в коде - более читаемый код (см. Стив Макконнель (http://www.stevemcconnell.com/books.htm) и другие)

Ответ 11

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

Ответ 12

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

Я бы предпочел иметь хорошие документы, конечно, но, учитывая выбор между плохими документами и медленно работая через исходный код, я возьму исходный вариант.

Ответ 13

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

Я бы предпочел, чтобы никакая документация не документировала плохую документацию.

Ответ 14

hmm.. вопрос, который вы задаете себе, - это плохая документация, или это неправильно, а код неправильный?

Например, в сводке говорится, что "эта процедура имеет значение xyz", но код на самом деле делает abc странным образом. Если часто бывает так, что резюме правильное - то, что должен делать код, но автор был полным nincompoop.

Я видел это чаще всего, когда речь заходит о кодах возврата, сводка дает хороший набор кодов, которые должны быть возвращены, но процедура возвращает 0 каждый раз.

В любом случае, его ошибка и должна быть исправлена ​​или, по крайней мере, отмечена комментарием. "Плохая" документация, которая обновляется, даже с "WTF"? меток лучше, чем никакой документации. Документация, которая выглядит устаревшей, просто не читается.

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

Ответ 15

Плохая документация хуже, чем отсутствие документации. Тем не менее, я бы сказал, что, насколько это возможно, ваш код должен быть самодокументирован. то есть вы должны выбрать значащие имена для объектов в вашем коде и иметь короткие методы. Комментарии, объясняющие, что делает код, должны быть фактически излишними, потому что это ясно из самого кода. Комментарии в основном будут использоваться, чтобы объяснить, ПОЧЕМУ ваш код что-то делает.

Ответ 16

Документация не намного лучше.

На самом деле, я готов идти дальше. Храните документацию на высоком уровне и не документируйте слишком много деталей.

Как только вы хорошо понимаете структуру высокого уровня, никакая документация не лучше понимания кода, читая код.

Я не верю, что кто-то работает над модулем, который не понимает, что именно делает этот код модуля. Если вы хотите использовать модуль как черный ящик, хорошо, прочитайте документ. Если вы хотите изменить свое поведение, почти лучше не давать вам документацию и выяснить, что она делает во всех случаях.

Ответ 17

Документация по коду важна, но ее совершенно незначительная по сравнению с Unit/Acceptance/Functional Tests. (Когда я говорю код doc, который я принимаю в отношении метода/класса doc не высокого уровня дизайна /api doc).

То, что должен был сделать ваш коллега, было написано кучей тестов, чтобы поддержать его предположение, а затем изменил документ.