Поясню сабж: процесс кодирования сильно зависит от специфики задачи и общего процесса разроботки (проектирования, тестирования, документирования). Комментарии в этом смысле можно отнести к различным потокам работы (workflow) или скорее к некотрой связке между ними. Поэтому возникает вопрос на каком этапе их писать? Можно писать сразу: закодил метод — закооментировал. Можно после успешной сборки, можно даже перед кодированием, а ля автотесты. Зачастую приходится слышать, как начальство требует комментарии, что лично мне, например, не убобно, потому как код постоянно меняется и их приходится переписывать, на что собственно уходит время. С другой стороны, если их не писать сразу, то потом когда все заработало и продается уже вроде и не надо как-то.
Вот и хочется услышать соображения на этот счет. Поделитесь опытом.
Здравствуйте, Ароан, Вы писали:
А>Добрый день.
А>... Поэтому возникает вопрос на каком этапе их писать? ... А>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.
Непосредственно перед написанием кода.
Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.
Здравствуйте, mrozov, Вы писали:
M>Здравствуйте, Ароан, Вы писали:
А>>Добрый день.
А>>... Поэтому возникает вопрос на каком этапе их писать? ... А>>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.
M>Непосредственно перед написанием кода. M>Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.
А еще лучше перед написанием кода писать тесты.
Тогда точно приходится задуматься над тем, что надо сделать
и как этим пользоваться.
Комментарии же бывают разные.
Интерфейсную часть комментирую сразу.
А детали реализации ближе к концу, если это вообще надо.
Бывает что комментарии просто не нужны, потому что все видно из самого кода.
Вообще конечно я с этом согласен в идеале. Но на практике порой бывает, что не совсем понятно, что писать. Например:
1. Требования заданы не четко, да еще и меняються постоянно. Мол сделай так, чтобы работало быстро и надежно, а как придумай сам.
2. Не отлажен процесс проектирования, пишешь кусок кода — показываешь. Конечно с этим надо бороться, но не так все просто, особенно когда патология укоренилась.
3. На этапе кодирования понимаешь, что чего-то не учел или что то, что задумано будет работать совсем не так как задумано (даже где-то в РУПе слышал такой термин, "перекрестное проектирование" так что ли, когда одновременно проектируют и кодируют). В итоге переписываешь кусок кода, меняется логика и комментарии пишешь заново.
Должен же быть какой-то компромис.
Здравствуйте, bkat, Вы писали:
M>>Непосредственно перед написанием кода. M>>Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.
B>А еще лучше перед написанием кода писать тесты. B>Тогда точно приходится задуматься над тем, что надо сделать B>и как этим пользоваться.
B>Комментарии же бывают разные. B>Интерфейсную часть комментирую сразу. B>А детали реализации ближе к концу, если это вообще надо. B>Бывает что комментарии просто не нужны, потому что все видно из самого кода.
Я комментарии почти не делаю, потому что знаю, что они очень быстро рассогласовываются с кодом, к которому они относятся и снижают понятность.
Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes.
Теперь, когда в MSVS 2005 есть рефакторинг, нормальные названия стало давать значительно проще.
Таков мой подход.
Здравствуйте, Ароан, Вы писали:
А>Вообще конечно я с этом согласен в идеале. Но на практике порой бывает, что не совсем понятно, что писать...
А>Должен же быть какой-то компромис.
Это да.
Только форум тут философский, потому рассуждаем об идеальных сущностях.
Реальность она частенько другая
С этим я тоже согласен. Но полюбому найдется такой кусок кода, который будет непонятен по коду. Особенно когда дело касается сложных алгоритмов или всеобщих архитектурных решений.
Здравствуйте, MatFiz, Вы писали:
MF>Я комментарии почти не делаю, потому что знаю, что они очень быстро рассогласовываются с кодом, к которому они относятся и снижают понятность. MF>Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes. MF>Теперь, когда в MSVS 2005 есть рефакторинг, нормальные названия стало давать значительно проще. MF>Таков мой подход.
Здравствуйте, MatFiz, Вы писали:
MF>Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes.
Вероятно забавно выглядят идентификаторы waitResponseTimeoutInMilliseconds или slaveHostConnectionTimeoutInSeconds
А для названий классов и методов есть какие-нибудь правила?
SObjectizer: <микро>Агентно-ориентированное программирование на C++.
Здравствуйте, eao197, Вы писали:
E>А для названий классов и методов есть какие-нибудь правила?
Канэшна!
Основных правил два
1. Название должно как можно более адекватно и кратко отражать то, к чему оно относится.
2. Следовать code-naming guidelines от Микрософта (поля на подчеркивание (и приватные, кстати), интерфейсы на I, контролы как nameTextBox или okButton, эвент-хэндлеры — с постфиксом Handler и параметрами вида (sender, EventArgs), протектедный метод OnEvent()).
Здравствуйте, Ароан, Вы писали:
А>С этим я тоже согласен. Но полюбому найдется такой кусок кода, который будет непонятен по коду. Особенно когда дело касается сложных алгоритмов или всеобщих архитектурных решений.
А это надо описывать не комментариями, а в отдельных дизайн-документах.
Или пишешь скажем ты какую-то библиотеку для других.
Ты же не будешь рассчитывать, что другие будут лезть в исходники,
чтобы понять как этим добром пользоваться.
Для этих целей надо писать специальный док, посвященный жтому аспекту.
Со сложными алгоритмами точно так же.
Надо писать отдельное описание без сильной привязки к реализации.
bkat wrote:
> А это надо описывать не комментариями, а в отдельных дизайн-документах. > > Или пишешь скажем ты какую-то библиотеку для других. > Ты же не будешь рассчитывать, что другие будут лезть в исходники, > чтобы понять как этим добром пользоваться.
Для этих целей лучше использовать какую-нибудь систему типа doxygen.
Видел как java-api документация описана? Прям в исходниках!
Posted via RSDN NNTP Server 2.0
но это не зря, хотя, может быть, невзначай
гÅрмония мира не знает границ — сейчас мы будем пить чай
Здравствуйте, AndrewVK, Вы писали:
AVK>Сразу писать, потому что иначе это начинает смахивать на профанацию.
Сразу это когда? Например я пишу их перед комитом. Раньше просто нет смысла ибо у меня методы в процессе кодирования постоянно появляются и исчезают или меняется их функциональность. К тому же для написания комментариев нужно переключить мозги на другой режим работы, а переключать мозги туда сюда не продуктивно к томуже такие переключения сбивают с мысли.
... << RSDN@Home 1.1.4 beta 6a rev. 436>>
Пусть это будет просто:
просто, как только можно,
но не проще.
(C) А. Эйнштейн
Здравствуйте, kan_izh, Вы писали:
_>Для этих целей лучше использовать какую-нибудь систему типа doxygen. _>Видел как java-api документация описана? Прям в исходниках!
Ага. Только отдельного документа описывающего архитектуру это ни в коем случае не отменяет. javadoc позволяет описать интерфейсы классов, а не то как они используются, для чего нужны или почему они спроектированны именно так. Стоит отметить, что комментарии в коде на эти вопросы обычно не отвечают. Поэтому, кстати, документацией на явовские классы, даже официальной, пользоваться менее удобно чем MSDN.
А>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.
Я стараюсь писать самодокументирующийся код. Это включает правильное именование переменных/классов, постоянный рефакторинг. Как показывает практика, хорошо спроектированный и хорошо написаный код в комментариях не нуждается. Сложные моменты, в которых без комментариев не разобраться, это первые кандидаты на рефакторинг. Если рефакторинг невозможен, например это реализация хитро оптимизированного алгоритма, применяется "литературное программирование": сначала человеческим языком описывается что делается, а потом в текст вставляется код. Делается это до написания, потому как такой код скорее всего меняться не будет, а описанный человеческим языком алгоритм намного упрощает кодирование. Архитектура описывается отдельным документом, в котором зафиксированы принятые архитектурные решения и причины, побудившия принять именно эти решения. Варианты использования описываются модульными тестами, которые также можно использовать в качестве примеров.
Не комментирую вообще, или только по просьбе. Если код непонятный, то комментарии не особо помогают(там чаще такую фигню пишут, лишь бы просто написать). Ежели код понятный, то смысла нет. Какой нибудь отдельный документ описывающий общую архитектуру и как это работает больше помогает для разбора, чем комментарии. Но все это мое IMHO.
Здравствуйте, GlebZ, Вы писали:
GZ>Не комментирую вообще, или только по просьбе. Если код непонятный, то комментарии не особо помогают(там чаще такую фигню пишут, лишь бы просто написать). Ежели код понятный, то смысла нет. Какой нибудь отдельный документ описывающий общую архитектуру и как это работает больше помогает для разбора, чем комментарии. Но все это мое IMHO.
Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек. Написание документации по библиотеки, которую будут использовать разные программисты с разными тараканами в голове -- это очень неблагодарное дело. Но хуже всего, что для библиотеки нужен Reference Manual про ее API. Самый удобный способ получения такого manual-а -- это написание специальных комментариев в коде которые затем обрабатываются специализированным инструментом (JavaDoc, Doxygen, RDoc, DDoc и пр.). Если при разработке библиотки комментарии не писать сразу, то задокументировать ее затем будет весьма трудоемким и, возможно, бесполезным занятием.
SObjectizer: <микро>Агентно-ориентированное программирование на C++.
Здравствуйте, eao197, Вы писали:
E>Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек. Написание документации по библиотеки, которую будут использовать разные программисты с разными тараканами в голове -- это очень неблагодарное дело. Но хуже всего, что для библиотеки нужен Reference Manual про ее API. Самый удобный способ получения такого manual-а -- это написание специальных комментариев в коде которые затем обрабатываются специализированным инструментом (JavaDoc, Doxygen, RDoc, DDoc и пр.). Если при разработке библиотки комментарии не писать сразу, то задокументировать ее затем будет весьма трудоемким и, возможно, бесполезным занятием.
Тут лучше сделать сразу две задачи.
1. Задокументировать с помощью Unit-тестов и(или) examples.(чаще полезней чем различные списки интерфейсов)
2. Задокументировать библиотеку, как — уже неважно. К вопросам комментариев мало относится. Как ты документируешь с помощью комментариев или просто вручную написав документ, твое личное дело. И к тому же оно совершенно не касается внутреннего кода.
Здравствуйте, WolfHound, Вы писали:
WH>Сразу это когда?
Сразу — это перед написанием метода.
WH>Например я пишу их перед комитом. Раньше просто нет смысла ибо у меня методы в процессе кодирования постоянно появляются и исчезают или меняется их функциональность.
Тут идея в том, что если ты сосредоточишься на том чтобы написать комментарий, то ты четко поймешь для чего на самом деле тебе этот метода нужен, и тебе не придется его десять раз переписывать.
Мы уже победили, просто это еще не так заметно...
