Комментирование?

Ответ 1

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

Ответ 2

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

Ответ 3

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

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

В книге Clean Code есть хорошая глава о комментариях.

Ответ 4

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

Ответ 5

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

Примерами этого являются Scala ScalaTest или RSpec для Ruby.

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

Помните, что код с устаревшими комментариями хуже, чем вообще никаких комментариев!

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

Просто используйте рамки тестирования.

Ответ 6

Вы еще прочитали код Complete? Рекомендовано как очень хорошее чтение, и отличный способ выяснить некоторые из вещей, которые CS profs сверлит вам горло.

Комментарии кодов представлены в двух вариантах:

• Комментарии для объяснения логики, убедитесь, что код соответствует намерение. Часто люди пишут высоко уровневого псевдокода и будет использовать это в форме комментариев, чтобы заполнить фактический код того, что модуль будет делать. Затем они оставляют комментарии как считывание, которое можно использовать во время последующего обзора.
• Комментарии к объясните использование модуля. Думать Javadocs. Ваше намерение здесь для потребителям понять, почему код важен. Одно использование javadocs находится в Visual Studio Intellisense (поскольку я не использую Eclipse idk). Он показывает комментарии от javadoc в intellisense парения. Вскоре ОЧЕНЬ удобно.

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

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

Но я определенно говорю, что прочитал эту книгу.;)

Ответ 7

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

Ответ 8

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

Это работает во многих случаях. Однако один из полезных комментариев - "почему" что-то делается. Иногда исправления делаются по неясным причинам, которые не были бы очевидны при просмотре кода позже. Комментарии не должны указывать, что делает код (который должен быть покрыт именованием) или как он это делает (опять же, код говорит вам об этом), поэтому сохраните комментарии для "почему".

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

Ответ 9

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

Что бы вы ни делали, НЕ пишите такие комментарии...

// add 1 to i
++i;

Этот шум. У вас на самом деле хуже, чем с комментариями.

Ответ 10

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

Вместо:

// Compute average for the two times
int a = t1 + (t2 - t1) / 2;

записи

int averageTime = AverageOfTimes(t1, t2);

int AverageOfTimes(int t1, int t2) {
    return t1 + (t2-t1); 
}

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

Лично я пишу объяснительный комментарий для каждого класса (в основном код на С# и С++), а иногда, когда я использую алгоритм, к которому я хочу обратиться.

Ответ 11

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

Ответ 12

Раньше я был в той же ситуации, что и вы. Когда я впервые начал, я никогда ничего не прокомментировал, потому что все было очень маленьким, и я всегда знал, как это работает. Но по мере того, как я продолжал расширять свой код, и все началось, указывая друг на друга, я обнаружил, что не знаю, что некоторые вещи сделали и потеряли. Мне пришлось переписать много вещей, чтобы я знал, что они сделали снова, и я начал комментировать все, чтобы я точно знал, как это работает и как использовать его в будущем. Вы можете подумать, что знаете, как все работает сейчас, но в будущем вы оглянетесь и скажете "HUH?". Теперь лучше прокомментировать вещи и потом сэкономить.

Как я комментирую вещи:

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

/**
 * What the function is supposed to do, a brief description of it.
 *
 * @param     paramter_name     Object-type     A description of it, do for each parameter.
 *
 * @return    Object-type - A brief description of what is being returned.
 **/

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

Ответ 13

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

Ответ 14

Я обнаружил, что, как вам все скажут - если вы вернетесь к коду через несколько месяцев, вы все забудете. Тем не менее, я почти не комментирую свой собственный код, за исключением комментариев типа // ew.. hacked because X-beyond-my-control doesn't do Y correctly. Но это потому, что сам код написан очень чисто и очень легко читается. Например, все имена переменных и функций являются полностью описательными. Я не использую аббревиатуры, за исключением довольно длинных слов, которые очевидны, например, "информация". Все функции чрезвычайно короткие. Все функции делают одно, если это возможно. Если это возможно, можно избежать. Логически связанные функции группируются через классы или модули.

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

Ответ 15

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

foreach(var a in b.Items) //Enumerate the items in "b"
{
    if(a.FirstName == "Jones") //See if first name is Jones
.... 

Вы хотите что-то посреди вышеизложенного и не комментируете вообще.

Ответ 16

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

Ответ 17

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

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

Ответ 18

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

Консистенция и соглашение также помогают. Старайтесь избегать NumberOfStuff, ThingCount, FooSize, всегда использовать ту же форму, возможно, что-то в соответствии с языком (имеет ли она Array.length или Vector.size). Всегда называйте похожие вещи с похожими именами.

"Код никогда не бывает. Комментарии иногда делают". Один день или другой, кто-то изменит код, а не соответствующий комментарий. Лучше spenf больше времени написание самоочевидного кода, дополненного некоторым умным комментарием, чем расщепление кода, а затем объяснение вещей с большим количеством комментариев.

Ответ 19

Правило № 1 Комментарии должны указывать, ПОЧЕМУ не "что" (код уже говорит вам "что" )

Правило № 2 После написания комментария - перепишите свой код, чтобы читать как комментарий (затем удалите комментарий)

Ответ 20

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

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

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