11

I'm documenting some code, and I have a private HashMap. I'd like to specify information about what is expected from the key and value. Right now I have:

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

However, this seems hard to read, and also like it won't work well when I have something more complex like

HashMap<String, HashMap<String, String>>

What are best/common practices for documenting maps?

LeahNH
  • 535
  • 1
  • 4
  • 12
  • I don't document maps, or other variables. They need to be simple and well named so that their usage is obvious, at least when observing code. Besides, if you document functionality, it doesn't matter what variables you use to end up with it. You can also replace the functionality with an equivalent one without caring about any variables used. – Kayaman Aug 11 '15 at 14:29
  • I agree with kayaman. the name of the map should be descriptive enough, along with the typing, for someone else to understand. – GregH Aug 11 '15 at 14:30
  • You may define new classes `Word`, `PartOfSpeech`, etc and then have a Map like `Map`. But it maybe over-engineered and depends on the domain you want to map. Anyway, you should declare the reference as `Map`, to not be bound at that point to a concrete map implementation. – PeterMmm Aug 11 '15 at 15:35

1 Answers1

8

If you need a small javadoc, I suggest the following:

/**
 * 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 keywork will redirect you on instance definition.

Note : Using an interface as a type (Map instead of HashMap) should be preferred.

André Blaszczyk
  • 750
  • 4
  • 17
  • What additional information does that JavaDoc provide? Everything is obvious from code in a more concise way. – qqilihq Oct 04 '15 at 08:20
  • Describe business rules. Object1 is a custom class which concerns only your project / you company for instance. For an object, method, class or package, you can write a bunch of functional specification. You should never guess what a method does. – André Blaszczyk Oct 04 '15 at 08:33