Comments 18
Кхм. Знаете, есть такой старый советский анекдот, который заканчивается "чего только не сделают, чтобы не ходить на овощную базу". Подход необычный, не встречался раньше.
Ну это я так… на самом деле вопрос такой — хорошо, вам это помогает все разбираться в проекте. Но как, черт возьми, вам это поможет в случае, когда проект делал Вася, и он уволился, не оставив хвостов?
А ведь еще и тот Петя, который придет после вас — для него ваши механизмы вполне могут оказаться китайской грамотой, он в них ничего не поймет, и в итоге тщательно выстроенный механизм развалится после очередного "рефакторинга".
при новом проекте мне поможет в том, что я найденное нанесу на "карту", а при рабочем проекте мне поможет в том, что при работе над сервисами коих 7+, мне не надо будет напрягать мозг и тратить силы и время на воспоминания что и как, а просто будет карта того что есть.. если придет "Петя" и не разобравшись начнет ломать и стирать, ну это же будет его проблема, так то он может теперь хотя бы не хабре прочитать - что к чему и зачем все эти аннотации в коде
Спасибо! Идея следует за книгой "Программист-прагматик". Из распространенных инструментов: PlantUML умеет работать в том числе и с Mind Map, GraphViz позволяет из текстового файла dot строить архисложные диаграммы. Недавно как раз использовал для визуализации конечного автомата в публикации где диаграмму генерировал код на Java.
Эти аннотации очень близки по смыслу к обычным комментариям. О проблеме комментариев подробно написал Р. Мартин. Их очень сложно поддерживать, и от этого они постоянно рассинхронизируются с кодом. Лучше писать код, который не нуждается в комментариях.
В вашем примере параметр note дублирует параметр url. При следующем изменении вы легко можете забыть его поменять при изменении метода.
Документировать нужно высокоуровневые архитектурные вещи, которые из кода бывает сложно извлечь и которые почти не меняются.
это уже вопрос лени разработчика, никто не мешает параметр URL сделать строковой константой и использовать её, но так как расположено это всё рядом, то можно и неособо заморачиваться
высокоуровневые архитектурные вещи и их документирование никак не решат проблему поиска мест реализации и неформализованного знания о её деталях
Проблема не в лени. Приведу пример из авторитетного источника, поскольку сам не мастер точно и красиво формулировать мысли.
Итак, вы оказались в ситуации, в которой необходимо написать комментарий?Хорошенько подумайте, нельзя ли пойти по другому пути и выразить свои намерения в коде Каждый раз, когда вам удается это сделать, — похлопайте себя по плечу. Каждый раз, когда вы пишете комментарий, — поморщитесь и ощутите свою неудачу.
Почему я так настроен против комментариев? Потому что они лгут Не всегда и не преднамеренно, но это происходит слишком часто Чем древнее комментарий, чем дальше он расположен от описываемого им кода, тем больше вероятность того, что он просто неверен. Причина проста: программисты не могут нормально сопровождать комментарии.
Программный код изменяется и эволюционирует. Его фрагменты перемещаются из одного места в другое, раздваиваются, размножаются и сливаются. К сожалению, комментарии не всегда сопровождают их — и не всегда могут сопровождать их. Слишком часто комментарии отделяются от описываемого ими кода и превращаются в пометки непонятной принадлежности, с постоянно снижающейся точностью.
Р. Мартин. Чистый код
Мартин предлагает использовать комментарии только в крайнем случае, а вы наоборот предлагаете ввести их как правило, что на мой взгляд не очень хорошо. Связи между классами можно получить из кода. Комментарии все усложняют в вашем случае.
а причем тут комментарии? тема не про комментарии, а про возможность вставить разметку средствами языка Java и потом вынести их в отдельное изоражение, для ыстрого онаружения, тогде уж это ближе к комментариям TODO чем просто к комментариям, но в отличии от комментариев, всё это жестко привязано к элементам и может в принципе вообще не иметь текстов, они будут извлечены из имен аннотируемых элементоы
При том, что такую документацию сложно поддерживать. Код все время меняется, и приходится все это дублировать в аннотациях. Если это какая то часто используемая либа, то этот подход может работать. Для прикладного, быстро меняющегося кода - это слишком затратно и ведет к множеству ошибок (расхождений между кодом и аннотациями).
да, документацию сложно писать, поддерживать, всё меняется постоянно (поэтому большинство контор на рынке сейчас или не пишут её или делают какую то пародию "что бы было") и поэтому я и сделал такое решение что бы минимизировать дистанцию между кодом и документацией, тогда шансы что она вообще будет и будет как то соотноситься с текущим состоянием дел - растут кардинально, ну конечно у тех кто хочет снизить себе боль в будущем
помню с разработчиками из постгреспро разговаривал, уточнял как они документацию держат. Они сказали, что просто реадми файлы в пакетах исходных кодов с описанием, тоже видать пришли к выводу что далеко от кода документация быстро станет чем то самостийным и оторванным от жизни
Документирование кода и комментарии - разные вещи.
Документирование - это описание "что" делает код. По моему опыту, ситуаций, когда функция меняет свою функциональность - крайне редки. Это сродни документировании внешних интерфейсов сваггером, только документируется внутренняя кухня.
В то же время комментарии - это описание "как" работает код. Вот это как раз может меняться и устаревать. И тут желательно выкручиваться понятным кодом.
Самодокументируемый код это очень круто. Жаль на практике самодокументируемый код - это свой код. И то, только пока его помнишь.
Проект интересный, но по сути сводится к комментариям, которые дают возможность построить визуализацию. Это удобно использовать в своих проектах. Это позволит писать меньше строк комментариев, а меня честно говоря раздражает, когда исходник - это на каждые три строки кода "двадцать" строк комментариев.
Есть минус. Нынче Java проекты становятся все более насыщены аннотациями, что в конечном итоге не сильно отличается от комментариев и добавляет уровень сложности в плане поиска и разбора функционала конкретного процессора аннотаций.
P.S.
Внимание! Мое мнение - это мнение самоучки. За сим прошу не кидать в меня камни, ведь умные книги, чаще всего тяжелее и толку от них будет больше)
А почему бы просто не сделать понятную структуру проекта? То же дерево получится. Ну разве что http методы не будут видны.
потому что если это не проект уровня hello world то структура спасет только отчасти и когда будет 1000+ файлов и десятки вложенных директорий, то непросто будет находить
но большой minp map, который, по сути, рисует то же дерево у вас, как я понимаю, только в виде "солнышка" тоже мало поможет. Ну либо у вас на карте получается более понятная структура, чем текущая структура папок. Но тогда что мешает сделать рефакторинг и перестроить структуру папок аналогично той структуре, котрую в mind map строится? Тогда не будет "лишнего" промежуточного слоя в виде аннотаций, которые могут начать отставать от развития проекта (как выше в комментариях отмечают)
А на сколько сложно сделать, чтоб плагин граф зависимостей между классами и пакетами строил на основании импортов?
У меня чаще в больших легаси проектах как раз задача правильно структуру проекта переделать, чтоб обеспечить low coupling, high cohesion и вот это вот все. Тулы для визуализации зависимостей очень этот процесс упрощают
Еще один путь снизить боль при работе с Java проектами и их документированием