Я работаю над проектом стажировки, но мне нужно уйти, прежде чем я смогу все закончить.
У меня есть 1 класс, который недостаточно стабилен для производственного использования. Я хочу отметить / пометить этот класс, чтобы другие люди не могли случайно использовать его в производстве. Я уже поместил уведомление в Javadoc, но этого недостаточно. Некоторые ошибки или предупреждения компилятора были бы лучше.
Код организован так:
[Package] | company.foo.bar.myproject
|-- Class1.java
|-- Class2.java
|-- Class3.java <--(not stable)
Если бы был один фабричный класс, который вызывает эти классы в открытых методах, я мог бы установить метод class3
как private
. Однако API НЕ выставляется таким образом. Например new Class1();
, пользователи будут напрямую использовать этот класс, но я не могу сделать класс верхнего уровня приватным. Как лучше всего справляться с этой ситуацией?
Ответы:
Почему бы просто не проверить все нестабильные классы в другой ветке в вашей системе контроля версий?
источник
Если вы правильно прокомментировали класс, вы можете пометить биты неполной функциональности как «устаревшие» и / или закомментировать внутренности метода и поставить a
throw new UnsupportedOperationException();
.См. Есть ли что-нибудь вроде .NET NotImplementedException в Java? для деталей.
источник
Я не знаю такого предупреждения компилятора.
В вашей ситуации я бы, вероятно, использовал
@Deprecated
аннотацию. Он будет зачеркивать вызовы методов, поэтому другим будет очевидно, что что-то не так. Когда они посмотрят, что происходит, они увидят ваши комментарии о «не готов к производству» и пойдут AHA.источник
Я не думаю , что есть стандартный способ маркировки коды , как
WIP
,Incomplete
или что - то в этом роде.Вы можете создать новое исключение с именем
ClassUnstableException
и затем вызвать его вClass3
конструкторе с сообщением, объясняющим, как им не следует его использовать. Это плохо, потому что он предупреждает их только во время выполнения.Вы также можете попытаться сделать класс каким-то образом несовместимым, а затем добавить примечание в раздел кода, который отключает компилятор, чтобы, если кто-то попытается исправить код, он, надеюсь, увидит объяснение того, почему ему не следует использовать этот класс. , Это может не работать, если они используют полуавтоматический инструмент «исправить эту проблему», который есть в некоторых средах разработки. Это также плохо, потому что это может сломать сборки.
Вы можете создать аннотацию с именем
WIP
(поскольку я могу подумать, что это наиболее близко,Deprecated
но на самом деле это не означает то же самое) и использовать ее для аннотирования класса. Это, вероятно, будет немного больше работы, и что будет поддерживать аннотацию?Наконец, вы можете просто добавить это в комментарии, но это сработает, только если люди действительно их прочитают .
РЕДАКТИРОВАТЬ:
Это может быть актуально: Как преднамеренно вызвать предупреждающее сообщение о компиляторе Java?
источник
Почему это там в первую очередь?
Вы проверили нестабильный код в магистрали? Почему?
Нестабильный код не должен быть зарегистрирован в trunk / main / master или как там есть основное имя транка. Это считается разработкой с высоким уровнем риска, и вместо этого она должна была быть изолирована в своей собственной ветке, над которой вы работали, а не проверена на main.
Я настоятельно рекомендую вам (и руководителю вашей команды) прочитать Расширенные стратегии ветвления SCM . В частности, обратите внимание на роль разработки и то, что в ней говорится о том, что считается развитием высокого риска:
Разрешение людям проверять нестабильный (или неиспользуемый) код в основной строке означает, что вы будете путать будущие усилия по разработке с попыткой сохранить этот код. Каждая ветвь и клон представителя с этого момента до конца времени будут содержать это, пока кто-нибудь не скажет «его мертвый код» и не удалит его.
Некоторые говорят, что «хорошо, если в ветке это забыто», и хотя это может быть правдой, забыть мертвый (и нестабильный) код в mainline во много раз хуже, так как он запутывает всю будущую разработку, пока он не будет удален - и тогда это еще более забыто. Красиво названная ветка "/ fooProject / branch / WeisBigIdea" (или эквивалентная) видна и с ней легче работать в будущем - особенно, если она работает.
@Deprecated
Первое - это
@Deprecated
аннотация. Это выходит за рамки javadoc и выдает предупреждения компилятора.javac
предоставляет-deprecation
флаг, который описывается как:Как уже отмечалось, это выходит за рамки стандартных предупреждений компилятора.
Во многих средах разработки устаревшие методы и значения показаны зачеркнутыми:
И будет производить вывод, как:
В зависимости от вашей структуры сборки, у вас могут быть предупреждения, нарушающие сборку. Это нарушит сборку только в том случае, если будет использован один из ваших классов (а не если он просто скомпилирован).
@CustomAnnotation
Есть много подходов к этому. Например, облегченная аннотация javac @Warning, которая предоставляет процессор аннотаций, который выдает предупреждение во время компиляции, когда используется что-то с этой аннотацией ( учебное руководство по netbeans на пользовательских процессорах аннотаций, чтобы вы могли получить представление о том, что происходит за сцены).
Oracle даже описывает пример использования пользовательских аннотаций для
@Unfinished
аннотации в статье Использование большинства метаданных Java, часть 2: Пользовательские аннотации .С AnnotationProcessor вы можете запускать произвольный код во время компиляции. Вам решать, что вы хотите от этого. Предупредить, сломать сборку, когда что-то используется. В Интернете существует множество учебных пособий по написанию такого рода кода. Если вы хотите сгенерировать ошибку при ее компиляции (это будет раздражать и привести к ее удалению), или если ее использовать (написать немного сложнее).
Обратите внимание, что все это подразумевает изменение сборок для фактического использования процессора аннотаций.
источник
Вы можете ввести обработку аннотаций времени компиляции, но это заставит всех членов команды корректировать процесс компиляции.
Однако я нахожу весь процесс немного запутанным. Нестабильный API должен быть четко отделен путем создания ветки в вашей системе контроля версий. Если он действительно должен быть в остальной части кодовой базы, был задокументирован как нестабильный и, тем не менее, используется, проблема не является на самом деле технической, а лежит внутри организации и коммуникации. Да, вы можете ввести технические проверки (например, обработку аннотаций), но это не решит проблему - просто переместите ее на другой уровень.
Поэтому я рекомендую: если вы не можете разделить кодовую базу, поместив ее в разные ветви, поговорите с людьми и объясните им, почему они не должны использовать API.
источник
Не могли бы вы переместить все неполные классы в подпакет с именем что-то очевидное, например "NOTCOMPLETE"? Это что-то вроде хака, но может быть достаточно заметным.
(Если они не все в одном пакете, вы можете воссоздать структуру пакета там.)
источник
Я не знаю, что есть действительно хороший способ сделать это в коде. Сделать шаг назад:
Создайте две копии всего проекта, один с классом, а другой без. Отметьте версию без класса как стабильную кодовую базу, готовую к производственному выпуску, а версию с классом как разработку для будущего выпуска. Документируйте, что должно произойти, прежде чем этот класс можно будет считать производственным качеством.
В идеале вы должны делать это с помощью веток в выбранном вами решении управления исходным кодом. Возможно, вам придется немного обмануть, поскольку, похоже, вы не использовали такую стратегию ветвления. Осторожно удалите новый класс, зарегистрируйте версию без него и проведите регрессивное тестирование. Когда вы убедитесь, что она стабильна, вы можете пометить эту ревизию, создать ветку разработки из тега, а затем добавить класс обратно в ветку разработки.
источник
Я бы предпочел сделать класс абстрактным и правильно прокомментировать - таким образом, код все еще там для справки, но удачи всем, кто пытается его реализовать :)
источник
Как насчет создания зависимости, которую компилятор не может разрешить? Просто добавь:
импортировать this.is.not.done.yet.do.not.use.it;
наверх Пользователи не смогут скомпилировать его.
Если вы хотите протестировать класс, просто создайте пакет / класс с этим именем (или используйте более простой, например, «Экспериментальный. Опасный»), и вы можете протестировать новый код.
источник