Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 18
Бесследные изменения
Не «бесследные», а неотслеживаемые. След изменения — это сам код (диф в версионнике). А его отслеживание — это как раз тикеты и дальше вверх.
Детальное документирование реализации и правда кажется лишним за исключением совсем нетривиальных случаев, сложных алгоритмов или предметной области. Но в таких случаях бывает достаточно одной строки типа
Или
Или
В большинстве случаев комментарии к реализации излишни. Хотите пояснить, что делает метод? Назовите его так, чтобы было понятно. Метод делает слишком много всего, в двух словах не расскажешь? Разбейте на более мелкие методы.
А вот комментарии к интерфейсам жизненно необходимы. Они рассказывают о контракте и спецификации: не как код работает, а как код должен работать.
// Расчёт ведётся по формуле 5.13.27 из техзаданияИли
// Corner case x == 0 is not handled as it's impossible in our caseИли
// Workaround of Stream.skip() problems in parallel streams, see http://stackoverflow.com/q/28521382/4856258 for detailsВ большинстве случаев комментарии к реализации излишни. Хотите пояснить, что делает метод? Назовите его так, чтобы было понятно. Метод делает слишком много всего, в двух словах не расскажешь? Разбейте на более мелкие методы.
А вот комментарии к интерфейсам жизненно необходимы. Они рассказывают о контракте и спецификации: не как код работает, а как код должен работать.
Метод делает слишком много всего, в двух словах не расскажешь? Разбейте на более мелкие методы.
Мне кажется это неправильной практикой. Если есть длинный метод и его можно разбить на еще несколько методов то класс уже будет несколько пухлым и сходу можно запнуться об эти методы когда будешь читать код класса. Я думаю лучше помечать кусочки метода комментариями. А если IDE позволяет то дать названия этим кусочкам и свернуть их.
Да нормально. Из практики:
В одном чисто российском проекте (в котором никаких зарубежных разработчиков нет и никогда не было) руководитель запрещает использовать русский язык для написания документации, только английский. Само по себе это обстоятельство достаточно безвредное, вот только при найме на работу никто уровнем знания английского у программистов почему-то не интересуются, в результате вся документация, скопившаяся в проекте — это какие-то корявые, убогие предложения из 5 слов, из которых непонятно, что автор пытался сказать, и которые не то, что не несут никакой полезной нагрузки, а даже мешают нормально работать.
В другом проекте видел, как было покрыто документацией в коде вообще всё — даже абсолютно самоочевидные вещи, типа атрибутов классов, из названия которых совершенно понятно, что они делают, или методов из одной строчки. Ну т.е. покрытие документацией ради 100%-ого покрытия документацией. А вот нормальной документации об общих принципах функционирования всей этой поделки не было ни строчки.
TL;DR: в ИТ полно всяких наркоманов, документацию в коде нужно писать только по делу и далеко не все могут её нормально писать.
В одном чисто российском проекте (в котором никаких зарубежных разработчиков нет и никогда не было) руководитель запрещает использовать русский язык для написания документации, только английский. Само по себе это обстоятельство достаточно безвредное, вот только при найме на работу никто уровнем знания английского у программистов почему-то не интересуются, в результате вся документация, скопившаяся в проекте — это какие-то корявые, убогие предложения из 5 слов, из которых непонятно, что автор пытался сказать, и которые не то, что не несут никакой полезной нагрузки, а даже мешают нормально работать.
В другом проекте видел, как было покрыто документацией в коде вообще всё — даже абсолютно самоочевидные вещи, типа атрибутов классов, из названия которых совершенно понятно, что они делают, или методов из одной строчки. Ну т.е. покрытие документацией ради 100%-ого покрытия документацией. А вот нормальной документации об общих принципах функционирования всей этой поделки не было ни строчки.
TL;DR: в ИТ полно всяких наркоманов, документацию в коде нужно писать только по делу и далеко не все могут её нормально писать.
А Вы точно внимально прочитали комментарий jsmiitty? Он как раз говорит, что документировать нужно, а в посте написана вот «такое»:
По идее, я против документации внутри ПО.
если код пишется одновременно с юнит тестами, то документация внутри кода не особо нужна, юнит тесты лучше помогают сделать код сопровождаемым, чем какой-нибудь doxygen.
Агу. Простая задачка: OSS-проект, публичный интерфейс, метод без документации. Как найти, что он делает, не покидая гитхаба?
Мы же об идеальном сферическом коде говорим, а не о конкретном проекте. Во первых нужно стремиться к тому, чтобы код был самодокументируемым, с понятными названиями функций. Во-вторых, если юнит-тесты писались одновременно с кодом, то они тоже будут на гитхабе. Если они не писались, тогда конечно нужна какая-то замена — например простыня комментариев перед каждой функцией.
Да не проблема: и названия функций понятные, и юнит-тесты на гитхабе есть (даже в том же репозитории). Вы же в названии контракт класса «а вот в таком случае возвращается такое, а в таком случае возвращается такое» и так далее не выразите? Так что возвращаемся к вопросу: как найти, что делает метод?
(заметим, придумать код идеальнее описанного сложно — если, конечно, не считать документацию частью идеала)
(заметим, придумать код идеальнее описанного сложно — если, конечно, не считать документацию частью идеала)
Если проект — это какая-то библиотека или SDK для внешнего использования — то конечно, документация должна быть, и желательно полная, это неотъемлемая часть продукта. Если же это вещь в себе, то полная документация всего внутреннего устройства, всех интерфейсов классов, и т.п. вещь совершенно не обязательная для того, чтобы его сопровождать. Если она есть — хорошо, но в реальных условиях она всегда запаздывает, ее мало кто из разработчиков обновляет.
Что делает метод в идеале должно быть понятно из его названия. Как его использовать и что он возвращает в разных ситуациях с разными параметрами — в случае идеально написанных и читаемых юнит-тестов можно понять из них.
Преимущество юнит-тестов над doxygen-style документацией — если их не обновлять — это сразу будет видно, тесты упадут, поэтому их вынуждены держать в актуальном состоянии. Но разумеется это все в сферическом случае.
Что делает метод в идеале должно быть понятно из его названия. Как его использовать и что он возвращает в разных ситуациях с разными параметрами — в случае идеально написанных и читаемых юнит-тестов можно понять из них.
Преимущество юнит-тестов над doxygen-style документацией — если их не обновлять — это сразу будет видно, тесты упадут, поэтому их вынуждены держать в актуальном состоянии. Но разумеется это все в сферическом случае.
Обычно коментарий ставят, чтобы пояснить, что делает нижестоящий кусок кода. Однако, как советуют многие, коментарии в коде должны отвечать на вопрос ЗАЧЕМ, а не на вопрос КАК. Последнее должно всегда быть понятно из кода.
Поэтому если кусок кода нетривиален, лучше его вынести в отдельную функцию и дать ей имя, поясняющее это действие. Таким образом в вышестоящей функции остаются только простые конструкции со смысловыми идентификаторами. Нужны детали — спускайтесь ниже.
На Java я иногда вместо создания новой функции отделяю рутину областью видимости, а результат записываю в переменную с поясняющим именем:
P.S. Что бы ни говорил автор, в реальной разработке со сжатыми сроками и ограниченным бюджетом очень сложно быть «святым». Впрочем, как и в реальном мире :)
Поэтому если кусок кода нетривиален, лучше его вынести в отдельную функцию и дать ей имя, поясняющее это действие. Таким образом в вышестоящей функции остаются только простые конструкции со смысловыми идентификаторами. Нужны детали — спускайтесь ниже.
На Java я иногда вместо создания новой функции отделяю рутину областью видимости, а результат записываю в переменную с поясняющим именем:
String myVeryImportantBusinessValue; {
// код, вычисляющий myVeryImportantBusinessValue
}
P.S. Что бы ни говорил автор, в реальной разработке со сжатыми сроками и ограниченным бюджетом очень сложно быть «святым». Впрочем, как и в реальном мире :)
Однако, как советуют многие, коментарии в коде должны отвечать на вопрос ЗАЧЕМ, а не на вопрос КАК. Последнее должно всегда быть понятно из кода.
Я вот для себя делаю чуть более сложное разделение:
- код отвечает на вопрос как
- именование и комментарии отвечают на вопрос что
- метаданные (комментарии к коммитам, тикеты, документация) отвечают на вопрос зачем
Любопытно, что в моём проекте for-fun у меня только один грех из семи, а на работе практически всё имеется в той или иной степени. Думаю, если спросить программистов, которые пишут опен-сорс проект забесплатно, зачем они это делают, многие ответят, что хочется почувствовать вкус правильного и безгрешного программирования, а не как обычно.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Семь смертных грехов разработки ПО