I am currently working on an library that can read and set config values on an device attached to a PC. Each of the config fields is described by a constant (public static readonly) object, which contains the name of this field, the type of its data (along with value restrictions) and the command sequences needed to read/write it.
This information is mostly just needed inside the library. However, client code needs to be able to tell the library to read/write specific fields, and I also want to pass collections of config values around in dictionaries that associate fields with their values. To do this, I need to provide public values which identify the fields.
Is it OK to use the same objects for internally describing the fields and for publicly identifying them? It feels slightly wrong, but I can’t put my finger on the reason. I hope you can either lay my doubts to rest, or tell me why it is a bad idea or what to look out for.
Update:
I ended up using the same objects for both the field identity and for implementing field access. Now, months later, I finally ran into an issue that highlighted why this was not quite a clean solution: A field object represents a config field on the device, as I noted above. This is independend from the way such a field is accessed.
In more general terms: My hidden, internal representation of the thing does not describe the thing. It describes something related to the thing which does not necessarily have a 1:1 relation.
This can become a problem if you want to alter the field access. For example, now I can’t create a Field decorator class that would offer “retry on error” access behaviour. Code working with the decorator would treat it as its own field, unrelated to the actual underlying field.
Note that this is not an answer to the original question, but rather a realisation that my assumptions were wrong. If you are really really sure that your internal description of your thing has a 1:1 relation to the thing itself, this problem does not apply.
This really depends on how your library functions and how the client code interacts with it. One potential issue with exposing the internal representation to clients is that you don’t have as much flexibility to change the internal representation without potentially breaking client code. However, I don’t think that would be too difficult to overcome, because at the point in time in which you need a different representation internally, you could just create a new internal representation, and leave the old representation as part of the public API.
If you decide to expose the internal representation as part of the public API, one thing to watch out for is unintended side effects. For example, let’s say client code passes you an object and then you store that object internally. Objects are passed by reference in C#, which means that any modification to that object would also occur to the one stored internally. Of course you could just make a copy of the object so that this problem doesn’t occur.
Lastly, you may want to step back and consider the public API from a client perspective (if you haven’t already). Perhaps try using it in some unit tests. You may find that the internal representation is not the best way to represent it from a client perspective.
For very simple API’s using the internal structure is probably ok. I always tend to lean the other direction, and would opt for an abstraction and an isolation in my design that segregates the public API from the inner workings.
It’s all about tradeoffs and just depends on what you’re trying to accomplish. Hopefully this will help your decision a little bit.