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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ extension = GetFileExtension ($ image_name);

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

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

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

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

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

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

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

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

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

EBITDA

и нет

EquityBeforeInterestTaxesDepreciationAndAmortization

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

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

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

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

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

//
// 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;
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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