Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 23
Комментарии как документация?
Ну да — Вы их написали и всё классно. Но код обычно меняется. И чаще всего те, кто его меняют, не будут менять комментарии. Забудут, не обтчратят внимание, поленятся. И будет у Вас нерелевантная документация в коде
Ну да — Вы их написали и всё классно. Но код обычно меняется. И чаще всего те, кто его меняют, не будут менять комментарии. Забудут, не обтчратят внимание, поленятся. И будет у Вас нерелевантная документация в коде
Еще быстрее устаревает обычная документация.
Это вопрос практики :)
Это вопрос практики :)
Чем принципиально отличается от того, что забудут поменять ия класса или контанты? В том топик был прмер MILLISECONDS_PER_HOUR = 2*60*60*1000L. Это лишь вопрос дисциплины и ответственности и он решается другими методами.
Если такая ситуация возникает часто — то это проблема не в комментариях, а в программистах. Ибо подобные товарищи сегодня забудут поменять комментарий, а завтра забудут проинициализировать переменную. Или еще что-нибудь забудут уже в коде. Так что это вопрос уже не в методологии оформления кода, а в уважении к товарищам по команде, которым в дальнейшем поддерживать подобный код с неактуальными либо отсутствующими комментариями.
Лично я придерживаюсь следующего подхода:
Когда комментарии не нужны? Когда код очевидный и самодокументируемый, по нему спокойно можно пробежать глазами, и сразу все понятно.
Когда комментарии нужны?
— Для автоматической генерации документации типа javadoc. Тот, кто будет читать эту документацию, не будет видеть перед глазами код, а будет видеть только документ, сгенерированый на основе комментариев. Иначе ему придется держать перед глазами еще и исходник, что сразу делает бессмысленым генерацию документации.
— При объявлении неочевидных констант, когда для объяснения смысла константы придется делать ее имя слишком длинным.
— Для пояснения каких-то деталей в коде, не связанных непосредственно с алгоритмом, но необходимых для адаптации к конкретному устройству или среде (например различных проверок, предположений, что вот здесь система будет вести себя определенным образом и т.п.).
— Для пояснения неочевидных алгоритмичесуих решений. Например с целью оптимизации.
Естественно, критерий «очевидности» у каждого свой в зависимости от опыта. Для кого-то деление побитовым сдвигом будет нуждаться в комментировании, для кого-то и сложные структуры данных и алгоритмы будут казаться очень легко читающимися и не нуждающимися в дальнейших пояснениях. Но стоит только помнить, что экономя свое время на написании комментария, ты отнимаешь его у коллеги, которому придется разбираться в твоем коде…
Лично я придерживаюсь следующего подхода:
Когда комментарии не нужны? Когда код очевидный и самодокументируемый, по нему спокойно можно пробежать глазами, и сразу все понятно.
Когда комментарии нужны?
— Для автоматической генерации документации типа javadoc. Тот, кто будет читать эту документацию, не будет видеть перед глазами код, а будет видеть только документ, сгенерированый на основе комментариев. Иначе ему придется держать перед глазами еще и исходник, что сразу делает бессмысленым генерацию документации.
— При объявлении неочевидных констант, когда для объяснения смысла константы придется делать ее имя слишком длинным.
— Для пояснения каких-то деталей в коде, не связанных непосредственно с алгоритмом, но необходимых для адаптации к конкретному устройству или среде (например различных проверок, предположений, что вот здесь система будет вести себя определенным образом и т.п.).
— Для пояснения неочевидных алгоритмичесуих решений. Например с целью оптимизации.
Естественно, критерий «очевидности» у каждого свой в зависимости от опыта. Для кого-то деление побитовым сдвигом будет нуждаться в комментировании, для кого-то и сложные структуры данных и алгоритмы будут казаться очень легко читающимися и не нуждающимися в дальнейших пояснениях. Но стоит только помнить, что экономя свое время на написании комментария, ты отнимаешь его у коллеги, которому придется разбираться в твоем коде…
чаще всего те, кто его меняют, не будут менять комментарии. Забудут, не обтчратят внимание, поленятся.История коммитов быстро покажет, кто будет бегать за пиццей весь следующий месяц, а кого и квартальной премии лишат :)
Ревью кода в таком случае подразумевает и ревью *docs в комментах, не так ли?
clang умеет проверять документацию. Хотя бы простейшие расхождения он уже будет находить.
Комментарий должен описывать базовые принципы работы функции/метода/поля/класса.
Будет очень странно если метод класса SQLTransfer.insert будет писать в файл. Как говориться, за такое руки отрывают :-)
И вот эти вот комментарии порой очень важны. Особенно, если программист пишет что-то совсем за облачное и далекое от стандартного. Хрен поймешь по коду потом что именно он написал.
Будет очень странно если метод класса SQLTransfer.insert будет писать в файл. Как говориться, за такое руки отрывают :-)
И вот эти вот комментарии порой очень важны. Особенно, если программист пишет что-то совсем за облачное и далекое от стандартного. Хрен поймешь по коду потом что именно он написал.
Почитал я статью, которая сподвигла вас к написанию сего поста и мне кажется вы её немного не так поняли. Как писал автор «Комментировать или не комментировать?» коментарии для документации писать надо, особено если вы хотите сделать документацию по паблик АПИ, это может стать удобно, особенно если следовать какой-нибудь структуре типо jsdoc. Однако коментировать код для «Комментарии помогают найти забытый код» звучит бредово, человек который будет работать с кодом потом, скорее всего кроме чувства недоумения ничего не успытает ибо врятли он будет искать код вашим методом, нужный код помогают искать правильная архитектура проекта и названия классов/методов/функций
Была неделя «Морского боя» на Хабре, теперь вероятно будет неделя «Комментарии в коде». Самым важным следствием явится то, что все будут поступать по прежнему, так как выработавшуюся за годы привычку сложно поменять.
Вы, вероятно, не дочитали пост от DreamWalker. В разделе «Когда можно и прокомментировать» вроде все хорошо изложено.
Я так подозреваю, что тут взаимопониманию сторон мешает различие в терминологии — многие javadoc (и аналогичную incode документацию) не воспринимают как комментарии.
Главное отличие вашего поста от предыдущего — у вас много комментариев и совсем нету кода. При этом половина статьи как не надо писать украшена кодом, а вторая, как надо без кода. Вы вторую часть вовсе не заметили, потому как привыкли читать только код, а на тексты избирательная слепота.
Тот пост нормальный.
Комменты к нему в стиле — а зачем комменты, если в thisIsMySuperSelfdocumentingCode все понятно — и вынудили пост написать?
Кстати, диагностика по постам в инете — это круче Ванги :)
Комменты к нему в стиле — а зачем комменты, если в thisIsMySuperSelfdocumentingCode все понятно — и вынудили пост написать?
Кстати, диагностика по постам в инете — это круче Ванги :)
Там был пост нормальный, но вы прореагировали только на первую часть и упустили вторую, где автор писал когда комментарии нужны.
>>thisIsMySuperSelfdocumentingCode
В оригинальном посте было про это
>>Когда можно и прокомментировать
>>Комментарии, которые повышают уровень абстракции
>>не всегда возможно подобрать краткие названия для классов
>>thisIsMySuperSelfdocumentingCode
В оригинальном посте было про это
>>Когда можно и прокомментировать
>>Комментарии, которые повышают уровень абстракции
>>не всегда возможно подобрать краткие названия для классов
Я не очень понятно пишу :((
Тот пост нормальный. ВЕСЬ.
Моя реакция — не на пост. А на комментарии к нему.
Очень много было — да я вообще не пишу комменты.
В первом уровне, к примеру.
>отсутсвие коментариев оправдано если код написан людьми для людей.
>Мы комментируем только нетривиальные участки кода, без которых не обойтись. В остальных случаях отдается приоритет простому и читабельному коду.
>Хорошая статья. Для себя давно выбрала не комментировать.
>Сейчас у меня уже сложилась некая практика, что комментариев почти не ставлю, чтобы не тратить время. Но иногда к коду нужно вернуться, чтобы поправить его. И если я с первого раза не вспоминаю, почему функция у меня работает именно так, то тогда пишу к ней уже комментарий.
Были и комменты, что комментировать код надо, и пошел холивар.
Я написал свое ИМХО, почему на практике комменты рулят и в каких случаях. Пишешь один — не тратишь время через год,
разбираясь, что и где.
Удобно в IDE подсказки иметь
Работаешь с чужим проектом — автогенерированная дока удобно, не лезя в код.
и т.д.
Тот пост нормальный. ВЕСЬ.
Моя реакция — не на пост. А на комментарии к нему.
Очень много было — да я вообще не пишу комменты.
В первом уровне, к примеру.
>отсутсвие коментариев оправдано если код написан людьми для людей.
>Мы комментируем только нетривиальные участки кода, без которых не обойтись. В остальных случаях отдается приоритет простому и читабельному коду.
>Хорошая статья. Для себя давно выбрала не комментировать.
>Сейчас у меня уже сложилась некая практика, что комментариев почти не ставлю, чтобы не тратить время. Но иногда к коду нужно вернуться, чтобы поправить его. И если я с первого раза не вспоминаю, почему функция у меня работает именно так, то тогда пишу к ней уже комментарий.
Были и комменты, что комментировать код надо, и пошел холивар.
Я написал свое ИМХО, почему на практике комменты рулят и в каких случаях. Пишешь один — не тратишь время через год,
разбираясь, что и где.
Удобно в IDE подсказки иметь
Работаешь с чужим проектом — автогенерированная дока удобно, не лезя в код.
и т.д.
Похоже, я дожил до того светлого дня, когда в программировании стало всё настолько хорошо, что пора обсуждать где нужны или не нужны комментарии, а больше и обсудить нечего
Вы забыли сказать, что изначально мало кто умеет писать правильные комментарии.
Но к этому приходят только те, кто их не избегает.
Те, кто пишут «самодокументированный код», просто никогда не освоят это искусство.
Но к этому приходят только те, кто их не избегает.
Те, кто пишут «самодокументированный код», просто никогда не освоят это искусство.
Я — автор поста про комментарии. Мне бы хотелось внести несколько уточнений.
Я не говорил, что комментарии писать не нужно. Я говорил, что если вам удалось написать такой код, который комментариев не требует, то это просто прекрасно. Значит тут комментарий по определению не нужен — он не привнесёт в проект ничего нового. Если код без комментариев непонятен, то пожалуйста — пишите комментарии. Только вот я агитирую за то, что если код получился какой-то непонятный, то лучше бы переписать сам код, чем компенсировать его комментариями. Но если не получается — то комментируйте, хуже от этого не будет. Главное — чтобы код был читаемым.
Если у нас имеется плохой программист, который пишет плохой код, но держит в уме правило, что «комментарии писать нельзя», то проблема-то не в правиле. Во-первых, правило звучит несколько иначе, я об этом только что написал. Во-вторых, рассмотрим случай когда он написал свой код без комментариев и считает, что он — идеальный. Кто вам сказал, что он написал бы нормальный комментарий к этому коду? Я встречал много случаев, когда код не очень понятен, а после чтения комментариев он становится непонятным вообще. Проблема в плохих программистах, которые выдирают из хороших практик к совершенному коду (до которого им ещё далеко) по одному предложению и начинают их применять везде подряд.
Что касается разработки документации через комментарии (JavaDoc и тому подобные), то кто я такой, чтобы вам запрещать это делать? Это вопрос не о совершенном коде, а методологиях разработки. И да, у меня в посте есть абзац про то, что если в команде решили писать документацию через комментарии, то это ваше решение, к совершенному коду это не относится. В статье-то большей частью обсуждаются совсем другие комментарии.
Но немного про совершенный код всё-таки скажу. Если вы ищите методы через комментарии к ним, то, наверное, что-то у вас ни так с названиями методов. Отличный пример того, как комментариями пытаются компенсировать плохие именования. Я в своих (даже весьма больших проектах) просто набирают по несколько первых букв слов, входящих в название (совсем не обязательно всех слов) — и IDE сама находит мне все нужные классы и методы.
Я не говорил, что комментарии писать не нужно. Я говорил, что если вам удалось написать такой код, который комментариев не требует, то это просто прекрасно. Значит тут комментарий по определению не нужен — он не привнесёт в проект ничего нового. Если код без комментариев непонятен, то пожалуйста — пишите комментарии. Только вот я агитирую за то, что если код получился какой-то непонятный, то лучше бы переписать сам код, чем компенсировать его комментариями. Но если не получается — то комментируйте, хуже от этого не будет. Главное — чтобы код был читаемым.
Если у нас имеется плохой программист, который пишет плохой код, но держит в уме правило, что «комментарии писать нельзя», то проблема-то не в правиле. Во-первых, правило звучит несколько иначе, я об этом только что написал. Во-вторых, рассмотрим случай когда он написал свой код без комментариев и считает, что он — идеальный. Кто вам сказал, что он написал бы нормальный комментарий к этому коду? Я встречал много случаев, когда код не очень понятен, а после чтения комментариев он становится непонятным вообще. Проблема в плохих программистах, которые выдирают из хороших практик к совершенному коду (до которого им ещё далеко) по одному предложению и начинают их применять везде подряд.
Что касается разработки документации через комментарии (JavaDoc и тому подобные), то кто я такой, чтобы вам запрещать это делать? Это вопрос не о совершенном коде, а методологиях разработки. И да, у меня в посте есть абзац про то, что если в команде решили писать документацию через комментарии, то это ваше решение, к совершенному коду это не относится. В статье-то большей частью обсуждаются совсем другие комментарии.
Но немного про совершенный код всё-таки скажу. Если вы ищите методы через комментарии к ним, то, наверное, что-то у вас ни так с названиями методов. Отличный пример того, как комментариями пытаются компенсировать плохие именования. Я в своих (даже весьма больших проектах) просто набирают по несколько первых букв слов, входящих в название (совсем не обязательно всех слов) — и IDE сама находит мне все нужные классы и методы.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
О комментариях в коде замолвите слово