Ale*_*ien 54
是的,您应该为私有方法编写JavaDoc,即使它仅适用于您自己.在3年内,当您必须更改代码时,您会很高兴您记录了它.
如果您离开公司,或者必须在另一个项目上工作,您的同事将很乐意提供记录在案的代码.未记录的代码具有更低的价值.
看看真正的专业人士是如何做到的.以下是Sun Microsystems的ArrayList类源代码的摘录:
/**
* The array buffer into which the elements of the ArrayList are stored.
* The capacity of the ArrayList is the length of this array buffer.
*/
private transient Object[] elementData;
ash*_*999 39
您需要问自己的第一个问题是"为什么要编写JavaDocs？" 他们对谁有用？谁让你写这些？
最有可能的是,有人(雇主/教授)要求您记录一些方法.这通常是一件好事,但需要付出代价:额外的维护.
如果您有一个可公开访问的文档版本(例如,如果您正在生成它们并在线发布给最终用户),那么记录最终用户需要知道的任何内容都是有意义的.这包括所有公共类和方法.
对你自己和其他开发者来说呢？
我的观点是你不应该在内部和私有方法和类上使用javadoc.主要原因是javadocs主要使那些使用而不是维护代码的人受益.
另一方面,您需要在自己的代码上保留注释和注释,这通常是内部代码.在这种情况下,我会建议正常的评论(例如//); 它的维护较少,而且往往同样清晰,打字少得多.
另一方面,如果方法变为公共方法,将这些注释转换为真正的javadoc可能很有用.Javadocs的好处是强迫您考虑(并记录)每个参数,异常和返回值.
需要权衡利弊.
不,你不应该为私有方法编写javadoc.最终用户无权访问私有字段或方法,因此没有必要为他们提供javadoc.私有字段和方法仅适用于开发人员.如果你真的需要,可以随意为不明显的逻辑写评论.您应该为protected方法编写javadoc,因为这些方法有时会被覆盖,并且向用户提供有关该方法的功能或应该执行的操作的一些信息是有帮助的.
您经常听到一般性建议,在最好的情况下,评论根本就没有必要.但是对于JavaDoc,它们不仅对开发人员而且对库的用户都起着重要作用.
另外,编写JavaDoc注释对于您(尤其是初学者)可能比对其他任何人更有用:当您发现很难描述变量是什么或者单个方法做什么时/** One-line-JavaDoc comment */,您将自动重新思考你在那里做了什么.
生成JavaDoc时,您可以选择是仅为API public和protected部分API 生成它们,还是为默认或private元素生成它们.
但是,在任何情况下都应该记录文档protected方法:扩展类的人只能调用此方法,还是允许他覆盖此方法？如果是这样,他应该知道任何先决条件和后置条件吗？他应该打电话super.theMethod()给被覆盖的版本吗？(顺便说一句:如果他不允许覆盖该方法,那么它应该是final,但无论如何都要记录)
顺便说一句:我个人评论一切,但知道大多数人认为这不是必要的,甚至是不好的风格,特别是对于"琐碎的"事物
/**
* The number of elements in this set
*/
private final int numberOfElements;
我认为这不会造成伤害,但在许多情况下会有所帮助.也许,关于private零件,这只是一个品味问题.
您不必编写任何 javadoc，但它非常有帮助。更多的 javadoc 从来都不是坏事。
根据您的问题，如果您使用 javadoc 文档编译器，javadoc 将针对受保护的方法进行编译，但不会针对私有方法进行编译。不过，没有理由不能将它们用作代码注释。