Есть ли способ для меня как-то разобрать мои файлы java-кода и искать комментарии к java-doc? Я хочу убедиться, что я написал javadocs для класса и каждого метода класса (или всего на самом деле). Это возможно?Как создать git-крючок, который заставляет меня писать комментарии javadoc?
Серьезный отказ от ответа: do не сделайте это. Последующие объяснения будут следовать; но весь мой вклад уходит корнями в большой опыт вокруг таких тем.
Дело в том, что рано или поздно (скорее раньше!) Вы столкнетесь с ситуациями, когда вы действительно хотите получить свои изменения в git. Зная, что вам нужно Javadoc, чтобы сделать это возможным, вы начнете подавляя фиктивный контент, например:
/** just to make the commit hook happy; @TODO: replace with real content */
И я вам гарантирую: рано или поздно вы обнаружите, что у вас есть много таких @TODOS гниения в вашем коде база для дней, недель, месяцев. Потому что в конечном итоге получение этой новой функции клиенту, оплачивающему вашу зарплату, более важно, чем исправление тех 15 @ TODO, которые вы получили где-то. Я сказал 15? Ах, это было на прошлой неделе. Теперь у нас есть 25 ... (LeBlanc's lawпозже не сравнится никогда пинки в Гарантированное!)
Другими словами: если вы хотели иметь документацию во всех местах, но ваша дисциплина не «достаточно хорошо» сегодня для достижения этого без такого рода принуждения; то это приведет к низкокачественному javadoc.
Помимо этого: после того, как мы сосредоточились на практике «чистого кода» в течение нескольких лет, я думаю, что сегодня: только с javadoc нет ответ. Хотя я работаю на большом предприятии с командами, разбросанными по всему миру.
напротив. Когда людей обучают писать «удобочитаемый» код, очень часто им фактически не нужны никакие (или просто крошечные кусочки) javadoc, чтобы добраться туда. Потому что тогда их дизайн и навыки именования находятся на том уровне, что код становится легко читать без большого количества javadoc.
И если люди не обучены этому умению, они склонны создавать бесполезный джавадок. Я не могу сказать вам, как часто я говорю людям отключить этот шаблон eclipse, который создает абсолютно бесполезный тег @author при создании нового класса. И угадайте, что: все еще есть бесчисленные вхождения javadocs, генерируемых затмением ..., которые были never, затронутые любым разработчиком после сгенерированного.
Короткий рассказ: ему нужно много дисциплины и навыков для создания javadoc. Если у вас уже не хватает дисциплины, тогда для принудительного применения правила «некоторые javadoc должны быть там» будет не повысить качество вашего кода!
И наконец: я не говорю, что не следует полностью рассматривать такие вещи.Но я предпочел бы предложить
Просто делайте то, что я должен делать;) – slim
Вы бы удивились, как часто приходится возвращаться и напоминать людям, чтобы они собрали свои +2 балла ;-) – GhostCat