For today's article we will focus on point 9: Keep it Simple to Use
This post is an extension of following post https://localwire.pl/throw-exception-at-me/. I found worth sharing my thoughts on this subject too :)
IList<User> = container.GetUsers("S*")
Developer A wrote "GetUsers(string pattern)" method in UsersModule. Developer B uses it.
Question: When B will ask A "Zero means 'no records' or also 'error connecting to database?'" ?
This is simple scenario where API is not well defined. It introduces uncertainty and questioning. It will make maintenance harder.
Developer A: I will throw exception if something bad occurs. Developer B: So I have to handle your DB issues ? In UI!? Developer C: I will be forced to do "great refactoring" in my module since it depend "heavily" on your methods....
Developer A: Let's return a boolean status. GetUsers method will return a tuple. A list and "tiny" boolean flag. Developer B: Great. I just check flag and know what to do. Developer C: It's polluting the API. It's like extra wrapper in boolean flag.....
How about considering every public method return object in UsersModule as "OperationStatus" ? We explicitly say that all methods are operations therefore they have status.
All developers have clear understanding what UsersModule can return. It's an
OperationResult<T> by definition.
This pattern was occurring so often that I decided to add
OperationResult<T> to HandlyLib. Here is the code:
[gist https://gist.github.com/pawelklimczyk/958f74a96e359bdb721b53065b3cd0ae /]
I would recommend using it in communication between layers. It has some overhead. Data has to be packed in extra "status" frame. I doubt it's worth doing that in in-module data flow. On the other hand it is worth investing time and effort to introduce it module-to-module communication, because it give us one and single way of handling statuses.
You can go even deeper and introduce Convention Tests (still looking for source of this term - mail me if you know something). It's fairly easy to do so with CodeWatch.
We tell CodeWatch to ensure that all public methods in UsersModule return
[gist https://gist.github.com/pawelklimczyk/cff77aec37c36f1a5650d18a94b855f0 /]
This way we can keep our code-base is more structured and better-defines form.comments powered by Disqus