Should methods returning a hashmap of string to object be avoided?

Question

In my current code I have felt the desire multuple times to have helper methods that generate a collection of objects and return them as a map of string to object, with the string being some unique id like the objects label. Many of my objects have gaurenteed unique labels since these labels are used via restful interface when querying the object.

The reason I want to do this is efficency. I may have a decent sized collection and I know that the method calling whatever private helper method I wrote will definately want to search for specific objects within my collection, so returning them as a map allows the calling method to run in O(n) instead of O(n^2).

However, I feel that the return is not self documenting. The key is just a string, there is nothing that makes it obvious that the string is specifically the objects label. Obviously I will have comments to that effect, but ideally self documenting code is writen so well one doesn't have to go to method delarations to figure something out.

So I have a few questions:

1) Is the fact that i find myself needing to return maps a code-smell in itself? (other then possibly premature-optimization, which I know I may be a little guilty of, but I don't feel too bad about worrying about the big O of a method)

2) Is this generally acceptable, or should I be looking into a cleaner approch? For instance should I have be making some map object that auto-maps any object by label? What about places that I want to return a map where the key is a different key, should I make a wrapping object for all of them? or is my map good enough?

EDIT:

More detail was asked, so to clarify my specific situation. I am working within java. While I may have unique strings they aren't known until compile time and enums are not a good fit, or I would have used them! I'm not using reflection or any other systems to dynamically generate data, the methods and their meaning is pretty much standard each time. Usually using the equivalent of a UUID of the objects (which in this case is a string which is used throughout the domain), or the label, which is a guaranteed unique string used to reference the object in question for a restful call.

Answer 1

The decision depends on many things:

• Is the caller method aware(at code-time) of the map's structure?
  When I say "code-time" I mean that when you write the code you have a specific structure in mind(compared to compile-time and runtime). If you don't, and the method should be able to handle any structure you throw at it(for example - a method for converting that map to JSON format), then you don't really need to document that structure outside the method that creates the map, since it doesn't need to be refered by a human outside the scope of that method.

• Are you using a static or a dynamic typed language?
  Dynamic languages tend to depend less on well defined data structures. In JavaScript, for example, there is no difference between an object and a map, and Ruby has OpenStruct that creates objects that are both structs and maps. When you don't have a strong type system you should be less strict about writing self-documenting code at the API level.

• Does the language you use provide a better way to do what you want?
  For example, many static typed languages have enum types, and you can often use those enum types as the keys of a map instead of string. This will allow you to have the self documenting code you want(the enum type declaration is a list of all keys used in that map) while still being able to iterate over all the key-value pairs without using reflection.

If you provide more details we might be able to provide more help.

Answer 2

Should methods returning a hashmap of string to object be avoided?

Yes, if you're using a statically typed language, object should be avoided. It means that you have to cast to do anything meaningful with the result, which means you have to modify any handling code when you add a new type. No good.

And string should be avoided as the key to a function/dictionary. Strings are easy to mistype/misspell. The strings often have implied contracts associated with them: if I ask for "foo", I want to get a Bar back. As soon as you don't get Bar stuff blows up - at runtime. No good.

Is the fact that i find myself needing to return maps a code-smell in itself?

For maps this generic, yes - for statically typed languages. It means that you want something to do anything which is about the worst violation of the single responsibility principle you can have. It also makes your contracts implied, which moves the errors from compile time to runtime, increasing the cost of fixing them and the risk that they make it to production.

Is this generally acceptable, or should I be looking into a cleaner approach?

You should always look for a cleaner approach, but in not a few cases you really do need something this generic. If you're doing serialization, you really need some string to object map... The goal here is to isolate the lack of typing as much as possible. Have a few classes that know about the possible strings and implied contracts. Push the design so that these classes change infrequently. Blow up loudly and promptly when the contracts are violated.

...and all of this goes out the window if you're working in a dynamic language. Pretty much everything there is already a map from string to object (which is another map of string to object), so the best you can do is play along and test like a madman.