python注释_不建议使用Java注释的正确方法

python注释

几乎没有什么@Deprecated没有适当的文档看到@Deprecated方法更令人生气的了。我感到失落。我应该仍然使用该方法吗？可能这不是开发人员的意图，这就是为什么他/她添加了弃用注释。我应该使用其他东西吗？所以…。

使用@Deprecated的规则是什么？

规则＃1：做Javadoc怎么做

每当您不赞成使用方法时，请创建一个JavaDoc，该JavaDoc告诉程序员如何不再使用该方法。不仅要说“不赞成使用此方法，请不要使用它”。这正是弃用注释和JavaDoc @deprecated单词所说的。没有必要用英语重复它。目标读者是Java程序员，应该知道弃用是什么意思。

为新方法命名，以替代旧方法。 (使用@link ！)这可能足够，也可能不够。新方法将包含一些说明如何使用它的文档。不要在JavaDoc中重复(文本或含义)。只是不要重复自己，文档也应该是DRY。另一方面，您可能需要描述如何用新的电话替换旧的电话。您可能会提示重构。

规则2：不要Javadoc如何

删除旧的JavaDoc文档。有人可能会争辩说，维护旧代码的用户可能仍然需要它。事实是，它们在库的旧版本中使用该方法的旧版本。旧版本的文档仍然存在，它们被冷冻刻在石头上(或者刻在存储库中的发行版中)。弃用该方法的实际版本不应包含过时的文档。这将鼓励程序员继续使用该方法。有一种使用不推荐使用的方法的方式：不使用它。如上规则1中所述，JavaDoc应该仅是当前的描述。

规则3：JavaDoc中不得道歉

不要在JavaDoc中解释为什么不赞成使用该方法。您是负责任的开发人员。这是你的决定。您做出了选择。其他人必须忍受它。如果您愿意，可以写一篇关于建筑决策背景的博客。这可能会有所帮助，但是JavaDoc并不是放置它的地方。

不推荐使用的API JavaDoc仅用于解释如何不使用。

重点是如何。不是“为什么不使用它”。

规则4：不赞成使用

如果您想弃用一种方法：那就去做吧！如果您害怕用户，并且不想让他们的生活悲惨地弃用某种方法，那么此决定将使您的生活变得悲惨。采取所有措施，以使API尽可能长时间不被弃用。但是，如果需要弃用某些东西，请立即扔掉。不要感到内，为什么在设计api时就看不到未来。我们谁也看不到未来完美。毕竟，生活对未来充满了无聊。

如果您对stakcoverflow有关此主题的意见感兴趣，请访问链接的页面。或者，如果您愿意，可以在这里开始一场火焰大战。我很

参考： Java Deep博客上的JCG合作伙伴Peter Verhas不赞成使用Java注释。

翻译自: https://www.javacodegeeks.com/2014/02/use-java-annotation-deprecated-the-right-way.html

python注释