Question

在记录代码时，我经常要编写方法。但是如何在文档中正确命名它们？

以下是一个例子：

要执行此任务，请使用someMethod()课程中的MyClass。

我也知道其他惯例：

（...），使用MyClass.myMethod()。
（...），使用MyClass#myMethod()。
（...），使用myObject.myMethod()。

哪种惯例最常用？有官方指南吗？

Answer 1

我认为您可以使用：

MyClass#myMethod()

因为订购多个标记部分中有类似内容： http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

...
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)
...

Answer 2

遵循"Don't make me think"格言，我建议使用以下格式：

To perform this task, use the someMethod method from the MyClass class.

此格式清楚说明目标方法和类是什么。

其他建议的格式，例如：

(...), use MyClass.myMethod().

(...), use MyClass#myMethod().

(...), use myObject.myMethod().

要求用户理解“。”的上下文。或者正在使用“＃”。

因此，无需用户暂停思考他们正在阅读的内容，只需使用（在编程领域几乎是通用的）单词“方法”和“类”来帮助清晰并消除任何可能的歧义。

如何在文档中命名方法？

2 个答案: