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

Question

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

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

Мысли?

РЕДАКТИРОВАТЬ: Это дало мне много думать. Спасибо за все Ваши ответы! Я никогда не ожидал такого большого ответа.

Answer 1

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

Answer 2

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

Answer 3

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

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

В книге Чистый код есть хорошая глава о комментариях.

Answer 4

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

Answer 5

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

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

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

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

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

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

Answer 6

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

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

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

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

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

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

Answer 7

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

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

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

Answer 8

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

Answer 9

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

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

// add 1 to i
++i;

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

Answer 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, когда я читаю чужой код. Некоторые авторы, в том числе авторы «Чистого кода», назвали чрезмерное комментирование «запахом кода».

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