Самодокументированный код Vs. Код комментирования

22

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

Ранее в этом месяце было сделано следующее сообщение:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

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

В приведенном примере

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Автор сказал, что к этому коду нужно дать комментарий, мое личное мнение таково, что этот код должен быть описательным:

$extension = GetFileExtension($image_filename);

Однако в комментариях кто-то на самом деле сделал именно это предложение:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Автор ответил, что комментатор был «одним из тех людей», то есть плохим программистом.

Каково мнение каждого из нас по поводу кода с самоописанием или кода комментирования?

Филл
источник
1
@ Петер - я взглянул на него, но больше хотел узнать мнение людей между ними, а не определять комментарии как запахи кода или нет.
Филл
2
Я нахожу эту статью ... ужасно читать. Очень обидно.
sevenseacat
@Karpie - я сделал :(
Филл
3
«Почему вы плохой программист на PHP» Ответ: Потому что вы программируете на PHP.
Томас Эдинг
Ваш предпочтительный метод по существу использует вызовы функций для комментирования вашего кода. Почему бы не использовать комментарии для этого? Функции должны использоваться только для кода многократного использования. Я лично ненавижу следовать чьему-либо коду, написанному таким образом, по той же причине, по которой утверждение GOTO является злом - оно создает код спагетти. Это улучшается современными IDE, но не каждый язык и программист могут использовать эти IDE, и это все еще дезориентирует. Честно говоря, я согласен с тем, что вам следует комментировать фрагменты кода, которые не ясны с первого взгляда - это просто делает чтение кода намного быстрее и проще.
Даллин

Ответы:

46

Я предпочитаю писать самодокументированный код. Руководством для этого является Чистый код .

Это, конечно, не означает, что никто не должен использовать комментарии - они играют свою роль, но ИМХО, вы должны использовать их осторожно. Этот мой более ранний ответ на SO объясняет мои мысли по теме более подробно.

Конечно, как отметил @Niphra, всегда стоит дважды проверить, что то, что я считаю чистым, действительно понятно другим. Однако это тоже вопрос практики. Вернувшись в универ, я написал загадочные кусочки кода просто из-за использования странных и забавных имен для всех сущностей кода, согласно моей прихоти. Пока мой учитель не отбросил одно из моих заданий, вежливо отметив, что он не мог выяснить, какой модуль был основным :-) Это был хороший урок, поэтому с тех пор я старался сосредоточиться на написании все более читаемого кода. В настоящее время я почти не получаю жалоб от товарищей по команде.

Петер Тёрёк
источник
Я люблю эту книгу :)
Филл
Я все еще нахожу комментарии ценными для выражения использованной стратегии и тех, кто был отклонен (с указанием причины). Я согласен, что микро комментарии вообще бесполезны.
Матье М.
9
Одна из моих любимых цитат из Чистого кода - то, что каждый комментарий - это неспособность выразить себя в коде.
Довал
6
@Doval: интересная философия, по крайней мере, в отношении комментариев о том, что делает код . С другой стороны, некоторые из наиболее полезных комментариев могут касаться того, почему код ничего не делает - концепция, которую я не думаю, что код должен выражать.
суперкат
1
Полностью не согласен. Никакое количество имен не будет полностью описывать цель логики.
Каньон Колоб
65

Вы не должны документировать, что делает код, но вы должны документировать, почему он это делает.

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

От всех остальных комментариев можно смело избавляться.

biziclop
источник
3
+1 Пример в связанной статье гласит: «Делайте комментарии в любой ситуации, когда цель написанного мною кода не сразу очевидна». - Просто глупо полагать, что код сам по себе может сообщать цель , потому что сами машины не имеют понятия цели. Встречный пример: у нас есть ошибки почти во всех когда-либо написанных программах, это правда. Если бы компьютер понимал цель ( почему ), он просто отказывался бы делать что-то кроме того, что мы намеревались, вместо того, чтобы покорно воссоздавать, что / когда / как / где это привело к ошибке.
Дэвид Мейстер,
Весь код внутри функции должен быть там, чтобы выполнить назначение функции, то есть то, что он делает, например, записать некоторый текст в файл, функцию «writeTo (String text, File file)». Если какой-то код имеет другое назначение, например, проверка предварительных условий, таких как проверка того, что файл существует, и это не очевидно, тогда, возможно, лучшей идеей, чем комментарий, является написание новой функции, например, «checkWritable (File file)». Качество кода не является догматическим контрольным списком, но если ему нужны комментарии, это плохой признак, и «почему» - не веская причина, чтобы нуждаться в них. Почему курица перешла дорогу?
Трюлкс
2
@Trylks Это работает для некоторых случаев, но не для всех. Представьте себе этот сценарий for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Теперь, это не является чем-то очевидным из назначения включающей функции и не может быть вынесено в ее собственную функцию. Если вы оставите это без комментариев, это явно плохо. Таким образом, вы добавляете комментарий, чтобы уточнить свои намерения.
Бизиклоп
2
@Trylks Кроме того, даже если мы возьмем ваш пример, вы включите проверку в метод и назовете его, отлично. Теперь все, что вам нужно объяснить, это то, почему вам нужно проверить, что файл доступен для записи. :)
Бизиклоп
38

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

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

Итак, прокомментируйте свой код. Конечно, не каждая строка (боже мой, нет), но поместите несколько строк комментария над функцией / подпрограммой / модулем или особенно сложной частью и вкратце расскажите, что она делает. Вы будете благодарить себя через год или два.

ладья
источник
Был там, сделал это. «Менее читаемый код» должен быть улучшен до кода, который хорошо читается. Знание языка на самом деле не имеет значения: если вы не знакомы с синтаксисом, вы должны сначала выучить его - честно говоря, это основа профессионализма. Попытка наверстать ужасный код, добавляя комментарии, не очень хорошая идея. Комментарии никогда не должны пытаться описать, что делает код. (Общий) комментарий оправдан, только если вам нужно сказать почему, а не что . Все остальное - просто шум и ненужные дополнительные вещи для обслуживания.
Powerslave
PS, я знаю, что вроде как "зомби" :) Извините за это
Powerslave
Чтобы избежать путаницы, я говорю об обычном случае, когда вас не заставляют писать плохой код в соответствии с бизнес-требованиями (например, исключительная производительность или встраивание в ограниченное хранилище). В других (редких) случаях у вас нет другого выбора, кроме как оставлять комментарии, что несколько облегчает бремя следующей жертвы.
Powerslave
19

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

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

Перекрывающиеся аргументы

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

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

Самоописывающий код

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

Больше комментариев

  • Комментарии более читабельны, чем код. Простой английский лучше при описании чего-либо.

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

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

Чтобы продемонстрировать, в книге « Чистый код» код разбит на многочисленные меньшие методы, которые вызываются только один раз. Методы создаются по единственной причине для документирования кода (и, проще, TDD). Это приводит к функции ада . Код менее читабелен, чем был изначально, и при рефакторинге не задумывались о том, чтобы инкапсулировать повторно используемый код.

С другой стороны, вы часто видите API, где каждая функция комментируется просто потому, что «комментарии хороши». Вещи, которые должны были быть прокомментированы, до сих пор нет.

Стивен Джеурис
источник
1
@Steven - «С другой стороны, вы часто видите API, где каждая функция комментируется, просто потому что« комментарии хороши ». Вещи, которые должны были быть прокомментированы, все еще нет». Тьфу, так досадно, правда!
dss539
Это очень хороший ответ! Одна вещь, если не возражаете, о читаемости комментариев: лично я не верю в то, что комментарии будут более читабельными. Мы, как разработчики, обычно думаем об исходном коде, особенно в «режиме кодирования». В те моменты неопределенность простого человеческого языка обычно больше отвлекает, чем помогает.
Powerslave
5

«Извините, но вы тот парень».

Интересно, почему он не любит комментировать: P

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

Посмотрите на грамотное программирование как на экстремальный стиль.

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

Короткий, лучший и правильный ответ

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

Гораздо лучший ответ, чем комментарии, следует использовать только для объяснения «почему» : комментарии должны:

  • объясните "почему" (конечно)
  • объяснять «что» в отдельных строках только тогда, когда код сложен или цель неясна, и это не может быть или не стоит упрощать дальше
  • объяснить «что» для блоков кода, чтобы ускорить понимание и найти то, что вам нужно

Объяснение, чтобы поддержать это

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

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

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

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

Даллин
источник
Я ненавижу, когда люди понижают голос и даже не оставляют комментарий, почему. Ты вообще прочитал весь пост? Что там не так просто и верно? С чем ты не согласен? Я чувствую, что люди настолько увлечены своей идеей или тем, что они читают, что даже не думают об этом и сразу же опровергают все, что не разделяет их мнение.
Даллин
3
Я предполагаю, что это потому, что вы прямо отвергаете и называете антипаттерн чем-то, что почти повсеместно признано правильным. Я, конечно, думаю, что вы зашли слишком далеко. В основном, я не могу себе представить доверчивые комментарии так, как вам кажется. Если вы слепо читаете комментарии, а не код, комментарии могут быть неправильными и устаревшими, и вы никогда не узнаете. Это основа использования функций в качестве документации. Я согласен, что у вас не должно быть слишком много функций в одном месте, хотя решение этой проблемы определенно не состоит в том, чтобы заменить их комментариями.
Волхв
@Magus Спасибо за комментарий. Я предполагаю, что вы имели в виду мои разговоры об использовании функций в качестве документации. Перечитывая это, я считаю, что я плохо сформулировал это, чтобы звучать так, будто я имел в виду, что использование функций для этой цели вообще (в отличие от чрезмерного использования функций для этой цели) было плохим. Я очистил этот абзац, чтобы уточнить мои первоначальные намерения. Я думаю о том, чтобы доверять комментариям: если комментарий становится устаревшим, обычно это признак того, что вы комментировали слишком узкий раздел кода - что вы комментировали реализацию, а не намерение.
Даллин
but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forЭто называется «имя метода / функции». Если у вас есть блок кода, у которого нет имени, но он настолько длинный, что вы не можете взять его одним быстрым взглядом, возможно, проблема в этом.
Бизиклоп
1
@biziclop Overtime Я пришел к выводу, что этот аргумент в основном является семантикой, и на практике наш код будет выглядеть аналогично. Сказав это, предполагая, что блок кода не используется более чем в одном месте, я не вижу разницы между блоком кода с коротким описательным комментарием вверху и блоком кода с коротким именем описательной функции в Вверх. Они одинаковые, кроме одного без пробелов. Они могут быть как ошибочными, так и устаревшими. Единственное отличие, которое я действительно вижу, заключается в том, что код легче читать с комментарием, поскольку вам не нужно следовать вызову функции в отдельном месте.
Даллин
2

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

user6791
источник
1
Можете ли вы привести пример. Я имею в виду приведенный пример в моем первоначальном вопросе. «GetFileExtension» Какой смысл в комментарии «Получает расширение файла данного файла»? Метод уже описал то, что должно войти в комментарий. Если бы метод назывался «GetExtension», тогда комментарий помог бы уточнить, что должен делать метод, поскольку метод не объясняет сам себя.
Филл
+1 Это вопрос для вашей аудитории. Кто может использовать эту функцию? Как вы можете им помочь? Сколько будет стоить ваша помощь? Стоит ли тратить больше времени на добавление комментария? И т. Д. И т. Д.
PeterAllenWebb
2
@PeterAllenWebb: нет никакого смысла в этом комментарии вообще. Это не означает, что функция не должна быть прокомментирована; должно. «Расширение» включает точку или нет? Для чего возвращается значение "foo"? ( null?? "") Для "foo."? Будет ли передача nullвызывать исключение, или функция будет возвращать что-то (возможно null)?
TJ Crowder
2

Что ж, с самодокументированным кодом то, что внутри этой функции вы найдете:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

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

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

Йорис Мейс
источник
Да. Я думаю, что вы должны быть "обучены", чтобы думать, что это должен быть один или другой, а не оба.
PeterAllenWebb
2

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

SK-логика
источник
Предполагая, что есть причина для всего, это должно быть прокомментировано?
JeffO
Да, именно так Вот почему я считаю, что лучший способ комментировать ваш код - это грамотное программирование.
SK-logic
1

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

$ extension = GetFileExtension ($ image_name);

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

Конечно, я немного растягиваю это. Но я помню программиста, который полагал, что audio_bandwidth и video_bandwidth были самодокументируемыми именами; Получившееся аудио должно было быть выражено в байтах, а видео - в килобайтах. Потребовалось много времени, чтобы понять это.

оборота Нифра
источник
5
Ты сильно растягиваешь это. Функция получает расширение имени файла. Ни больше ни меньше. Его имя говорит, принимает ли он массив или нет (явно нет). Я не могу придумать метод, который бы полагался на тип файла, чтобы получить расширение. Защита строки - единственная, которая может быть включена, но я бы никогда этого не ожидал, потому что, как знает любой PHP-разработчик: все пользовательские данные являются подозрительными, поэтому защитите их, прежде чем использовать их.
Мэтт Эллен
2
@Matt: «Ясно, что нет» является признаком того, что вы не часто выполняете техническое обслуживание. Будучи явным, в дальнейшем экономит много времени (и RTFSource), а также документирует, чего ожидал первоначальный автор . В комментариях или в длинных именах функций это не так важно.
Донал Феллоуз
Может быть, этот пример был плох для использования в этом вопросе, я не касался PHP около 7 лет, занимался C # и чуть-чуть Java, поэтому я привык иметь IDE, которая сообщает мне возвращаемый тип или объявляя типы.
Филл
1
@Donal Fellows: он говорит, файл, единственное число. Что в этом неоднозначного? Это полностью явно.
Мэтт Эллен
4
Тот факт, что в настоящее время есть 7 ответов от 4 человек, обсуждающих очевидность или нет единственного вызова функции, подсказывает мне, что вам нужно использовать комментарии . Это также подчеркивает тот факт, что точное именование само по себе является формой искусства.
Муравей
1

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

gablin
источник
Я думаю, что это относится к моему мнению, что «код должен быть описательным и в большинстве случаев не требовать комментариев, если код не может быть самоописываемым». Если вы пишете код, который написан хорошо, но не в полной мере объясняет смысл кода, тогда комментарии помогают сделать код более наглядным.
Филл
Код никогда не может объяснить его цель. Когда вы видите молоток, вы не можете понять, для чего он - для разбивания черепов или просто для ковки сырого железа.
SK-logic
1
@ SK-логика:public <T> void hit(T item);
Майкл К
@ Майкл - точно. Как пользователь будет выяснять, какие категории объектов можно и нужно забивать? Даже с намного лучшей системой типов не всегда ясно, какой диапазон возможных применений фактически запланирован разработчиком.
SK-logic
1

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

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

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

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

Sergio
источник
1

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

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

EBITDA

и нет

EquityBeforeInterestTaxesDepreciationAndAmortization

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

JeffO
источник
1

Я думаю, что мы должны различать документацию и выразительность кода.

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

Если вы хотите «прочитать книгу» определенного класса или функции, гораздо лучшее место для этого - в модульных тестах. Хорошо спроектированные модульные тесты по своей природе выявляют намерения и гораздо больше документируют (т. Е. Объясняют, детализируют), чем самые толстые блоки комментариев, поскольку они содержат 1 / ожидания относительно того, что должен делать этот код и 2 / возможность проверки эти ожидания против реального кода. Проходной тест в сто раз надежнее любого комментария с точки зрения документации, потому что он доказывает, что то, что он утверждает, является правдой.

guillaume31
источник
1

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

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}
работа
источник
1

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

Abbafei
источник
0

В университете нас учили перефразировать каждую строку кода на английском языке с комментарием (возможно, просто чтобы мы привыкли понимать, что код делает на самом деле, а не просто копировать / вставлять что-то и надеяться на лучшее).

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

ИМО: Самодокументированный код - это код, в котором имена переменных и методов имеют значимые и контекстные имена, чтобы они описывали, какова их цель.

Джеймс Лав
источник
0

Если вы неоднократно пересматривали свой код и до сих пор не нашли способ прояснить намерение тому, кто знает домен. Перепишите функцию. Ведь это не более 10-20 строк. Если это больше, переписать функцию в любом случае, это долго, и это часть того, почему это не читается :) rinse-repeat

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

Проще говоря, не пишите, вы комментируйте их

руны ФС
источник
0

Проверьте Code Complete 2-е издание, стр. 128-129.

Абстрактные типы данных избавят вас от этой головоломки. Самодокументированный код - это путь. Комментарии могут быть полезны, но имея

сущности реального мира, а не реализации низкого уровня

Вы можете избежать использования комментариев.

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

Комментарии действительно полезны, когда они интерпретируются IDE, как работает Delphi 2009+ или JavaDoc, но это скорее структурированный язык разметки, так что в некотором смысле вы программируете свою документацию, которая очень умна.

Питер Тернер
источник
0

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

Coyote21
источник
0

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

Если вы просто помните об этом, когда программирование / программирование?

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

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

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

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

Проверьте http://thedailywtf.com у них есть тонны юмористических, но реальных историй о программистах, которые только не сделали их должную осмотрительность ..

crosenblum
источник