Больше комментариев лучше в средах с высоким оборотом?

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

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

Комментарии не загромождают код.

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

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

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

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

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

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

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

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

Цель состоит в том, чтобы сделать кодовую базу легкой для понимания и изменения. Вы можете сделать это, хотя и свободно используете комментарии (хотя вы можете столкнуться с проблемой из комментариев к данным), или вы можете написать самодокументируемый код (насколько это возможно), и использовать комментарии только для объяснения нетривиального «почему» " вопросы. Любой подход может сработать, но учтите, что для изменения кода вам нужно понимать сам код, а не только комментарии. Поэтому, хотя комментарии могут помочь вам понять код, в конце концов вам, вероятно, все равно придется понимать сам код. С учетом сказанного я предпочитаю подход самодокументируемого кода. Кажется, это более прямой способ создания чистой кодовой базы.

"Являются ли больше комментариев лучше в средах с высоким оборотом?"

Я думаю, что они могут быть еще хуже

• Разные авторы будут использовать разные стили и уровни детализации и меньше будут обновлять комментарии других людей.

• Мнение «Что нужно комментировать» меняется от человека к человеку.

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

• Поддержание их формата и последовательности становится работой само по себе.

• Новые пользователи должны изучить стандарт «формат», прежде чем они смогут быстро вносить изменения.

Пункт 1: ясность важна в условиях высокой текучести

Пункт 2: многословие не ясность

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

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

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

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

• Лучшие имена переменных и функций
• Лучшее расположение кода и пробелы
• Удалите все "уловки", которые вы считаете хорошей идеей
• Группируйте код в соответствии с концептуальной функцией (например, извлекайте код для конкретной цели в функцию с соответствующим именем, даже если вы вызываете ее только один раз)
• Используйте более простой алгоритм (если позволяют условия)
• Используйте общеизвестные библиотеки для общей функциональности

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

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

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

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

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

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