Как вы думаете, код самодокументируется? [закрыто]

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

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

С моей точки зрения, я могу читать Java, Python, Delphi и т. Д., Но если мой менеджер подходит ко мне и спрашивает, как далеко я продвинулся в проекте, и я говорю: «Код завершен на 80%» (и до ты начинаешь меня сбивать, я слышал, как это произнесено разработчиками в нескольких офисах), как именно это самодокументируется? Извиняюсь, если этот вопрос кажется странным, но я бы лучше спросил и получил некоторые мнения по нему, чтобы лучше понять, почему он будет задан кому-то в интервью.

Частично.

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

Для сравнения:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

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

Нет. Код сам по себе не является самодокументированным.

Причина в том, что код указывает, КАК и не заботится о ПОЧЕМУ, что люди должны знать, чтобы поддерживать код.

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

Правильный код говорит вам « как ». Правильные комментарии говорят вам « почему » .

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

Если они настаивают на черно-белом ответе без разрешения, ответ будет отрицательным.

Более полный ответ заключается в том, что код должен самодокументироваться в максимально разумной степени, но нет разумного способа включить некоторые типы документации в код. Просто, например, код мог бы хорошо документировать, какая информация собирается в форме A, что в форме B и что в форме C. Как правило, он не будет (и, вероятно, не должен) пытаться документировать тесты, показывающие, что разделение данные, полученные таким образом, уменьшили количество ошибок на x% по сравнению с (например) использованием только двух форм вместо трех.

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

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

Тем не менее, существуют ограничения на то, что можно сделать, сделав код понятным. В этих случаях вы должны документировать.

Как насчет случая, когда у вас есть выбор о документировании? Я считаю, что обслуживание сильно зависит от вашей организации. Если у вас есть отличные разработчики программного обеспечения и строгий процесс проверки кода (как, например, у Google), то ваш процесс и люди могут быть такими, что вам не нужно беспокоиться о том, что комментарии не будут поддерживаться. В этом случае гораздо более насыщенный комментариями стиль имеет большой смысл. (На самом деле у Google есть стиль, насыщенный комментариями.) Однако, если у вас более типичная организация, я буду сильно не доверять любым комментариям, которые я вижу, и я буду надеяться, что у вас есть люди, которые поверили в попытке сделать код самодокументирующим. В этой ситуации я буду считать комментарии излишними.

Для интересного разговора о достоинствах и недостатках комментирования см. Http://www.perlmonks.org/index.pl?node_id=65153 для старого разговора, частью которого я был. (Обратите внимание, в то же время, когда у нас был этот разговор, был частный набор чатов, которые были более дружелюбными. Я всегда сожалел о том, что только более отрицательная половина разговора является публичной.) Мои мнения больше не соответствуют тому, что я тогда думал Но я все еще думаю, что разговор имеет полезную пищу для размышлений.

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

В идеальном мире можно сделать следующее заявление:

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

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

1. Программисты часто не являются экспертами в отрасли, против которой они программируют. Достаточно легко понять функцию, такую ​​как startEngine(Car car)(большинство) каждый может понять, о чем здесь спрашивают. Но переходите в реальный мир, и все становится немного размытым. Например, эта функция getSess(String tid, String aid)была бы совершенно понятна транспортному инженеру, который разбирался в системах DWDM, но она может стать проблемой для нового программиста, только что ставившего проект. Хорошо размещенные комментарии могут помочь облегчить переход к пониманию кода своевременно.

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

3. Сколько раз вы писали немного кода, который потом пытался понять, почему вы это сделали или даже чего пытались достичь? Мы все делаем это время от времени. Решение проблемы и простое решение проблемы - это два разных подхода. Если вы не тот человек, который может идеально написать код из шлюза, вы часто совершаете много ошибок в своем коде по ходу работы. Вы также можете не иметь возможности вернуться к этому фрагменту кода некоторое время. Хорошо размещенные комментарии могут помочь облегчить переход к пониманию кода своевременно.

4. Уникальные ситуации требуют объяснения. Например, программист может задаться вопросом, почему пауза в 100 мс была вставлена ​​в код, связывающийся с устройством DWDM. Сообщение следующему программисту о необходимости сделать паузу, потому что устройство медленно запускается и может пропустить команду, что будет иметь большое значение для получения информации. Хорошо размещенные комментарии могут помочь облегчить переход к пониманию кода своевременно.

Приятно написанный «самодокументируемый» код - это радость для поиска. Хорошо написанный «самодокументированный» код с хорошо размещенными информативными комментариями - находка, и очень редкая находка.

Просто чтобы привести аргументы с каждой стороны исходного вопроса:

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

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

Суть вопроса: даете ли вы частичный ответ, признавая ограничения ответа, или вы слепо опираетесь на ту сторону, которая, по вашему мнению, является лучшей практикой? Насколько вы уверены в своем ответе, если это да или нет? Это может быть воспринято как стрессовый вопрос, предназначенный для того, чтобы вызвать у кого-то ответ, который может ответить: «Что за…? Это самый глупый вопрос, который вы можете мне когда-либо задать. мой разум вне веры! как довольно высокомерный и напыщенный ответ, что я мог бы представить некоторых людей, дающих ответ таким тоном.

Очевидно, он был грамотным программистом в стиле Кнута. Для ученика LP код должен быть самодокументированным, чтобы быть действительным. Таким образом, единственный возможный ответ - «да».

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

Я считаю, что интервьюер, возможно, искал: «Как вы пишете самодокументированный код?» с подтекстом "Как вы относитесь к документации?"

Однажды я пошел на действительно вдохновляющую лекцию парня по имени Роберт С. Мартин, где он рассказал о главе «Методы письма» своей книги «Чистый код».

Он явно представлял немного о позиции пуриста, но я учел его совет: когда вы разбиваете код на небольшие многократно используемые методы и используете простые приемы, такие как:

• Хранение всех операторов в методе на одном уровне абстракции
• Извлечение содержимого условия потока управления или блоков цикла в вызовы методов
• Когда вы обнаруживаете, что передаете одни и те же параметры в несколько методов в классе, отделяете новый класс
• И простые приемы, такие как замена загадочных логических выражений вызовами методов.
• так далее...

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

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

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

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

Так что да, код самодокументируется. Насколько хорошо это задокументировано - это совсем другой вопрос.

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

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

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

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

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

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

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

Конечно, если у вас есть неограниченное время. Я провел более 25 лет, документируя код для других разработчиков. Моя позиция всегда состояла в том, что я пытаюсь объяснить что-то, чтобы другой разработчик мог ухватить это за 5 минут, когда они могли бы просто изучить код и выяснить это за полчаса. Если я спасу всех, кто смотрит на этот метод, на 25 минут, то я выполнил свою работу.

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

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

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

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