如何在Java中将类标记为正在开发中

我正在实习项目，但是我必须离开后才能完成所有工作。

我有1个类别不够稳定，无法用于生产。我想标记/标记该类，以便其他人不会在生产中意外使用它。我已经在Javadoc中发出了通知，但这似乎还不够。一些编译器错误或警告会更好。

代码的组织方式如下：

[Package] | company.foo.bar.myproject
          |-- Class1.java
          |-- Class2.java
          |-- Class3.java <--(not stable)

如果只有一个工厂类以公共方法调用这些类，则可以将方法设置为class3as private。但是，API不会以这种方式公开。用户将直接使用这些类，例如new Class1();，但是我不能将顶级类设为私有。处理这种情况的最佳做法是什么？

为什么不将所有不稳定类都检查到版本控制系统的另一个分支中呢？

如果您已正确注释了该类，则可以将不完整功能的某些部分标记为“已弃用”，或者注释掉该方法的内容，然后放置一个throw new UnsupportedOperationException();。

请参阅Java中是否有类似.NET的NotImplementedException？有关详细信息。

我不知道这样的编译器警告。

在您的情况下，我可能会使用@Deprecated注释。它将取消方法调用，因此对于其他人来说很明显有问题。当他们查看最新消息时，会看到您对“尚未准备好生产”的评论，并进行AHA。

我不认为这是标记代码的标准方法WIP，Incomplete或者类似的东西。

您可以创建一个名为的新异常ClassUnstableException，然后在Class3构造函数中引发该异常，并显示一条消息，说明他们不应使用该异常。但是，这很糟糕，因为它仅在运行时警告它们。

您也可以尝试以某种方式使该类不可编译，然后在使编译器跳闸的代码部分中添加注释，以便如果有人去修复该代码，他们将希望看到为什么不应该使用该类的解释。。如果他们使用某些IDE具有的半自动“修复此问题”工具，则此方法可能不起作用。这也很糟糕，因为它可能破坏构建。

您可以创建一个名为的注释WIP（因为我能想到的最接近的注释，Deprecated但这并不意味着同一件事），并使用它来注释该类。这可能需要更多的工作，什么将支持注释？

最后，您可以将其放在注释中，但这仅在人们实际阅读它们的情况下才有效。

编辑：

这可能是相关的：如何故意导致自定义Java编译器警告消息？

为什么首先出现在这里？

您已将不稳定的代码签入主线了吗？为什么？

不稳定的代码不应检入trunk / main / master或其他主干名称中。这被认为是高风险开发，应该将其隔离在您工作的自己的分支中，而不要检查到主要分支中。

我强烈建议您（和您的团队负责人）阅读Advanced SCM Branching Strategies。特别要注意开发角色及其对高风险开发的说明：

通常，考虑为每个高风险项目使用单独的分支。高风险项目的特点是规模大，人员多，主题不熟悉，技术主题高，时间表紧迫，交付日期不确定，要求不完整或不稳定以及项目团队的地理位置分散。同样，考虑为每个发行版中的低风险开发指定一个分支。包括[WING98]在内的一些来源建议为此使用主线。在采取此行动之前，请考虑以上针对主线讨论的因素。即使您有多个通过主线进行协调的产品系列成员，低风险开发也可能会与主线采取不同的策略。

让人们将不稳定的（或未使用的）代码检查到主线中，意味着您将在尝试维护此代码时混淆将来的开发工作。从现在到时间结束为止，rep的每个分支和克隆都将包含该副本，直到有人说“其死的codE”并将其删除。

有些人说“好吧，如果它在分支中会被遗忘”，虽然这可能是正确的，但在主线中遗忘了死（和不稳定）的代码会变得更糟，因为它会使所有未来的开发困惑，直到被删除为止；并且那就更被遗忘了。可以很好地看到“ / fooProject / branches / WeisBigIdea”（或等效名称）的分支，并且将来更容易使用-尤其是在这种情况下。

@Deprecated

首先是@Deprecated注释。这超出了javadoc的范围，并吐出了编译器警告。javac提供一个-deprecation标志，描述如下：

显示对不赞成使用的成员或类的每次使用或覆盖的说明。不使用-deprecation，将javac显示使用或覆盖不赞成使用的成员或类的源文件的摘要。-deprecation是的简写-Xlint:deprecation。

如上所述，这超出了标准的编译器警告。

在许多IDE中，不推荐使用的方法和值都带有删除线：

foo.bar();

并会产生如下输出：

$ javac -Xlint:all Foo.java Bar.java
Bar.java:2: warning: [deprecation] Foo in unnamed package has been deprecated
interface Bar extends Foo { }
                      ^

根据您的构建结构，可能会发出警告，警告您中断构建。如果使用了您的一个类，这只会破坏构建（如果只是简单地编译进来，则不会）。

@CustomAnnotation

有很多方法可以做到这一点。例如，轻量级javac @Warning批注提供了一个批注处理器，当使用带有该批注的东西时，它会在编译时发出警告（有关自定义批注处理器的netbeans教程，因此您可以了解场景）。

Oracle甚至@Unfinished在充分利用Java的元数据，第2部分：自定义注释中描述了使用自定义注释作为注释的示例。

使用AnnotationProcessor，您可以在编译时运行任意代码。真正由您决定要做什么。警告，在使用某些东西时破坏构建。网上有很多教程，介绍如何编写此类代码。是要在编译时生成错误（这很烦人并导致其被删除）还是要使用它（编写起来要复杂得多），是要生成错误。

请注意，所有这些都意味着将构建更改为实际使用注释处理器。

您可以引入编译时注释处理，但这将强制团队中的所有成员调整其编译过程。

但是，我发现整个过程有些混乱。不稳定的API应该通过在版本控制系统中创建分支来清楚地分开。如果确实必须在代码库的其余部分中，并且已被证明是不稳定的并且仍然被使用，则问题不是真正的技术问题，而是组织和通信中的问题。是的，您可以引入技术验证（例如批注处理），但这不能解决问题-只需将其移至另一个级别即可。

因此，我的建议是：如果无法通过将代码库放在不同的分支中来分离代码库，请与人们交谈并向他们解释为什么他们不能使用API​​。

您可以将所有不完整的类移到一个子包中，该子包的名称类似于“ NOTCOMPLETE”吗？这有点hack，但可能足够明显。

（如果它们不在同一个包中，则可以在此处重新创建包结构。）

我不知道在代码中确实有很好的方法可以做到这一点。退后一步：

创建整个项目的两个副本，一个带有类，一个不带类。将不带类的版本标记为稳定的代码库，以供生产发布，并将带类的版本标记为将来的发行版。记录在将此类视为生产质量之前需要进行的记录。

理想情况下，应该在所选的源代码管理解决方案中使用分支来执行此操作。不过，您可能不得不作弊，因为听起来您没有使用过这样的分支策略。仔细删除新类，检入没有新类的版本，然后进行一些回归测试。当您满意它的稳定性时，可以标记该修订版，从该标记创建一个开发分支，然后将该类添加回该开发分支。

我选择使该类抽象化，并进行适当的注释-这样，代码仍然可以作为参考，但是对尝试实例化它的任何人都表示好运:)

产生编译器无法解决的依赖关系怎么样？只需添加：

导入this.is.not.done.yet.do.not.use.it;

到顶部。用户将无法对其进行编译。

如果要测试该类，只需创建一个具有该名称的包/类（或使用更简单的名称，例如“ experimental.danger”），然后即可测试新代码。