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

Question

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

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

Мысли?

EDIT: Это дало мне много о чем подумать. Спасибо за все Ваши ответы! Я никогда не ожидал такого большого ответа.

Answer 1

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

Answer 2

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

Answer 3

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

Answer 4

Раньше я был в той же ситуации, что и вы. Когда я впервые начал, я никогда ничего не прокомментировал, потому что все было очень маленьким, и я всегда знал, как это работает. Но по мере того, как я продолжал расширять свой код, и все началось, указывая друг на друга, я обнаружил, что не знаю, что некоторые вещи сделали и потеряли. Мне пришлось переписать много вещей, чтобы я знал, что они сделали снова, и я начал комментировать все, чтобы я точно знал, как это работает и как использовать его в будущем. Вы можете подумать, что знаете, как все работает сейчас, но в будущем вы оглянетесь и скажете «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. 
**/ 

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

Answer 5

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

Answer 6

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

Answer 7

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

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

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

Answer 8

Если код хорошо написан, с короткими методами (см. Рисунок Composed Method) и meaningful names, тогда код нуждается в очень небольших комментариях. Только комментарии, объясняющие «почему», полезны - комментарии, объясняющие «что», должны быть заменены путем улучшения кода настолько, что очевидно, что он делает. Комментарии не должны использоваться as an excuse для написания плохого кода.

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

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

Answer 9

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

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

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

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

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

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

Answer 10

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

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

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

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

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

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

Answer 11

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

Что бы вы ни делали, не писать комментарии, как это ...

// add 1 to i 
++i; 

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

Answer 12

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

Вместо:

// 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 в. Превосходство было названо «запахом кода» нескольких авторов, в том числе авторов «Чистого кода».

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

Answer 13

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

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

Answer 14

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

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

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

Answer 15

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

Answer 16

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

Answer 17

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

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

Answer 18

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

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

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

Answer 19

Правило № 1 Комментарии должны указать, почему не «что» (код уже говорит вам «что» происходит)

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

Answer 20

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

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

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