Больше комментариев в коде или просто простом, читаемом, удобном в сопровождении коде достаточно? [закрытый]

Это, вероятно, что-то сделать в функции .onLoad, что-то вроде этого в вашем пакете:

NAMESPACE <- environment()

la. <- function(){ 
  ls(all = T, envir = globalenv())
}

.onLoad <- function(libname, pkgname) {
  makeActiveBinding("la", la., NAMESPACE)
}
10
задан Lonzo 13 February 2009 в 13:34
поделиться

13 ответов

Комментарии не должны там объяснять, что Вы делаете. Они там для объяснения, почему Вы делаете его.

30
ответ дан 3 December 2019 в 13:23
поделиться

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

Прокомментируйте разделы, которые не самообъясняют. Тривиальный комментарий (например, я ++;//Добавляют 1 к, i) делает код тяжелее для чтения.

Между прочим - чем ближе псевдокодировать Вас, может работать, тем большим количеством самообъяснения Ваш код может стать. Это - полномочие высокоуровневых языков; трудно сделать самообъяснение ассемблерного кода.

5
ответ дан 3 December 2019 в 13:23
поделиться

Аргумент основан на ложной дилемме: Или Ваш код является ужасным отвращением, и Вы пишете тонны комментариев для объяснения каждого оператора и выражения, или код является красивой поэзией, которая может быть понята под бабушкой без документации вообще.

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

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

Это может быть полезно при ловле ошибок. Грамотный код может выглядеть совершенно законным будучи абсолютно неправильным. Без комментариев другие (или Вы шесть месяцев спустя) должны предположить о Вашем намерении: Вы означали делать это, или действительно ли это был несчастный случай? Действительно ли это - ошибка или является ею где-то в другом месте? Возможно, я должен обратиться к проектной документации... Комментарии являются встроенной документацией, видимое право, где Вам нужен он.

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

12
ответ дан 3 December 2019 в 13:23
поделиться

Почему Вам нужны комментарии. Название метода должно быть достаточно ясным, что Вам не нужны комментарии.

Исключая:

//  This method is used to retrieve information about contact
public getContact()
{
}

В этом случае getContact не нужны комментарии

1
ответ дан 3 December 2019 в 13:23
поделиться

Не весь код самодокументирует.

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

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

2
ответ дан 3 December 2019 в 13:23
поделиться

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

1
ответ дан 3 December 2019 в 13:23
поделиться

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

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

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

0
ответ дан 3 December 2019 в 13:23
поделиться

Только прокомментируйте, когда это добавит что-то.

Что-то вроде этого бесполезно и определенно уменьшает удобочитаемость:

/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
0
ответ дан 3 December 2019 в 13:23
поделиться

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

Если необходимо записать комментарий. Сделайте это коротким. У меня часто есть чувство что, если необходимо уточнять долго то, почему этот блок кода делает это и что у Вас уже есть проблема с дизайном.

0
ответ дан 3 December 2019 в 13:23
поделиться

Читаемый код должен быть приоритетом номер 1. Комментарии, как Paul Tomblin уже записал, чтобы сфокусироваться на почему часть.

0
ответ дан 3 December 2019 в 13:23
поделиться

В основном, откладывая пользу, но возможно краткий комментарий в начале класса/метода/объявления функции, и - при необходимости - вводный комментарий в начале файла, комментарий был бы полезен, когда not-so-common или not-so-clearly-transparent операция кодируются.

Так, например, необходимо постараться не комментировать, что очевидно (я ++; на предыдущем примере), но то, что Вы знаете, менее очевидно, и/или более хитрый должен заслужить некоторой ясной, незапутывающей, блестящей, полной строки комментария, который естественно приходит с Нобелевской премией за самый четкий код в истории ;).

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

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

И лично я не большой поклонник самодокументирования кода (иначе кодируют w/o единственный проклятый slashstar): после месяцев Вы записали это (это - только дни для моего персонального масштаба), вероятно, что Вы не могли сказать истинной причине выбора такого дизайна представлять ту часть своего интеллекта, поэтому как мог другие?

Комментарии не являются просто той огородной зеленью среди строк кода; они - часть кода, который Ваш мозг лучше готовый скомпилировать. При квалификации как braincode (смех), который я не мог подтвердить, комментарии не являются частью программы, которую Вы пишете. Они - просто часть его, которая не направлена к ЦП.

0
ответ дан 3 December 2019 в 13:23
поделиться

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

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

0
ответ дан 3 December 2019 в 13:23
поделиться

Обычно, я - поклонник комментариев для документации, которые ясно обстоятельно объясняют намерение кода, который Вы пишете. Элегантные инструменты как NDoc и Замок из песка обеспечивают хороший, последовательный путь, которым можно записать ту документацию.

Однако я заметил несколько вещей за эти годы.

  • Большинство комментариев для документации действительно не говорит мне ничего, что я не могу действительно подобрать из кода. Это предполагает, конечно, что я могу сделать орла или решку из исходного кода для начала.

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

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

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

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

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

0
ответ дан 3 December 2019 в 13:23
поделиться
Другие вопросы по тегам:

Похожие вопросы: