Java中应该有什么javadoc?

发布于 2024-09-27 17:01:31 字数 271 浏览 9 评论 0原文

javadoc 注释应该记录哪些内容(类、方法、构造函数和字段?或者仅类方法和构造函数?)?有这方面的约定吗?

请尽可能在您的答案中提供相关资源的链接。 谢谢

编辑: 问题不在于通常是如何完成的,或者使用 javadoc 进行注释的逻辑是什么。问题是在任何 Sun/Oracle 官方文档(有关编写 javadoc、约定、规范等的指南)中可以找到有关此问题的内容。另外,请不要回答 javadoc 注释应该是什么样子,问题具体是关于应该注释什么,而不是如何注释。

What should be documented by javadoc comments (classes, methods, constructors and fields? Or only classes methods and constructors?)? Is there any convention about that ?

Please provide links to relevant resources in your answer whenever possible.
Thank you

EDIT: The question is not about how is it usualy done or what is logical to comment with javadoc. The question is what can be found about this matter in any official Sun/Oracle documents (guidelines about writing javadoc, conventions, specifications and so on). Also please do not answer about how should the javadoc comments look like, the question is specifically about what should be commented, not how.

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

评论(3

红衣飘飘貌似仙 2024-10-04 17:01:31

Javadoc 用于记录代码的公共 API。

简而言之,您需要记录所有公共和受保护的类、方法、构造函数和字段(因为您的用户可以访问它们)。

您需要描述方法的作用,而不是它是如何做的。当然,如果实现细节导致有趣的副作用,例如性能特征以及使用限制,则应该提及这些。

Oracle 有关于“如何为 Javadoc 工具编写文档注释的官方指南”。

Javadoc is to document the public API of your code.

In a nutshell, you need to document all your public and protected classes, methods, constructors, and fields (because they are accessible to your users).

You need to describe what a method does, not how it does it. Of course, if implementation details result in interesting side-effects, for example performance characteristics, and also usage limitations, those should be mentioned.

Oracle has official guidelines on "How to Write Doc Comments for the Javadoc Tool".

我是男神闪亮亮 2024-10-04 17:01:31

Thilo 提到的以及这里提到的 javadoc 的简单和一般规则应该如下:

Javadoc 指南

一般规则

  • 所有公共和受保护的方法都必须有完整的文档
  • 简单的 getter 和 setter 不受此规则的约束。正在做
    除了退货或更改之外什么都可以
    getter 或 setter 中的变量应该
    记录下来。
  • 具有非显而易见实现的私有方法应该足够
    允许其他人的文档
    开发人员调试它们

官方指南可以在这里找到:如何编写文档注释对于 Javadoc 工具

Simple and general rules for javadoc as mentioned by Thilo and also from here should be as follows :

Javadoc Guidelines

General Rules

  • All public and protected methods must have full documentation
  • Trivial getters and setters are exempted from this rule. Doing
    anything but returning or changing a
    variable in a getter or setter should
    be documented.
  • Private methods with non-obvious implementations should have enough
    documentation to allow other
    developers to debug them

Official guidelines are found here : How to Write Doc Comments for the Javadoc Tool

凉宸 2024-10-04 17:01:31

想象一下将代码展示给熟悉编程语言的其他人,而不是您的项目。当你看着他复习时,无论你觉得需要解释哪些部分,都应该记录下来。

关于programmers.SE的类似问题:你应该记录所有内容还是只记录大部分内容?

Imagine showing the code to someone else who is familiar with the programming language, but not your project. Whichever parts you feel the need to explain as you're watching him review it should be documented.

similar question on programmers.SE: Should you document everything or just most?

~没有更多了~
我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
原文