使用 JavaDoc 记录地图的标准方法是什么？答案

【问题标题】：What is the standard way to use JavaDoc to document a Map?使用 JavaDoc 记录地图的标准方法是什么？
【发布时间】：2015-11-03 20:12:37
【问题描述】：

我正在记录一些代码，并且我有一个私有 HashMap。我想指定有关键和值的预期信息。现在我有：

/**
 * HashMap where key=word, value=part of speech
 */
private HashMap<String, String> dictionary;

但是，这似乎很难阅读，而且当我有更复杂的东西时它也无法正常工作

HashMap<String, HashMap<String, String>>

记录地图的最佳/常见做法是什么？

【问题讨论】：

我不记录地图或其他变量。它们需要简单且命名良好，以便它们的使用是显而易见的，至少在观察代码时是这样。此外，如果您记录功能，那么最终使用什么变量并不重要。您也可以用等效的功能替换该功能，而无需关心使用的任何变量。
我同意 kayaman。地图名称应具有足够的描述性，以及打字，以便其他人理解。
你可以定义新的类Word、PartOfSpeech等，然后有一个像Map<Word, PartOfSpeech>这样的映射。但它可能过度设计并且取决于您要映射的域。无论如何，您应该将引用声明为 Map，以便在该点上不绑定到具体的地图实现。

标签： java dictionary hashmap javadoc

【解决方案1】：

如果你需要一个小的 javadoc，我建议如下：

/**
 * Dictionary is a {@link Map} collection that contains {@link Object1} as
 * key and {@link Object2} as value.
 */
private Map<Object1, Object2> dictionary = new HashMap<>();

@link 键将在实例定义上重定向您。

注意：最好使用接口作为类型（Map 而不是 HashMap）。

【讨论】：

JavaDoc 提供了哪些附加信息？一切都以更简洁的方式从代码中显而易见。
描述业务规则。 Object1 是一个自定义类，例如仅涉及您的项目/您的公司。对于一个对象、方法、类或包，你可以编写一堆功能规范。您永远不应该猜测方法的作用。