java - 如何在文档中命名方法？

Question

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

这是一个例子:

To perform this task, use someMethod() from MyClass class.

我知道还有其他约定:

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

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

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

哪种约定最常用？有官方指南吗？

Answer 1

遵循"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().

要求用户理解“.”所在的上下文。或正在使用“#”。

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