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.
Best Answer
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
OpenStructthat 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.