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

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

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

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

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

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

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

Я обнаружил, что, как все вам скажут, если вы вернетесь к программированию через несколько месяцев, вы все забудете. Тем не менее, я почти не комментирую свой собственный код, за исключением комментариев типа // фу .. взломан, потому что X -yond-my-control неправильно выполняет Y . Но это потому, что сам код написан очень чисто и очень легко читается. Например, все имена переменных и функций полностью описательны. Я не использую сокращений, за исключением довольно длинных слов, которые очевидны, например, «информация». Все функции предельно краткие. Если возможно, все функции выполняют одно действие. По возможности избегают гнездования. Логически связанные функции сгруппированы по классам или модулям.

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

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

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

// add 1 to i
++i;

Это шум. С такими комментариями вам будет хуже, чем вообще без них.

Я был в той же ситуации, что и вы. Когда я только начинал, я никогда ничего не комментировал, потому что все было очень мало, и я всегда знал, как это работает.Но по мере того, как я продолжал расширять свой код, и все начало указывать друг на друга, я обнаружил, что не знаю, что делают определенные вещи, и заблудился. Мне пришлось переписать много вещей, чтобы я снова знал, что они делают, и начал все комментировать, чтобы точно знать, как это работает и как использовать это в будущем. Вы можете думать, что знаете, как все работает сейчас, но в будущем вы оглянетесь на что-нибудь и скажете: «Ага?» Лучше комментировать сейчас, а потом избавить себя от неприятностей.

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

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

/**
 * 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.
 **/

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

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

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

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

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

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

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

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

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

Вместо:

// 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++), и иногда, когда я использую алгоритм, на который хочу сослаться.

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

Комментарии к коду бывают двух видов:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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