Friday, July 15, 2016

Many parameters and lost information

The less code, the better? The fewer objects, the better? Is it true? As usual, it depends.

There are cases when by adding something more we are adding unnecessary complexity. It happens when we are creating interfaces or other abstractions just because “we may need this additional flexibility in future”. It happens when we forget about YAGNI principle and we are writing code that may make our life easier in case of new requirements that… may never come.

On the other hand we have got situations similar to the one I described in my recent article. I showed you an example where we added a few methods that internally are doing almost the same. Yet, by adding them we gained a lot - the code became easier to understand. This additional code gave us information about WHAT the object is doing instead of HOW it is achieved.

Today I would like to share with you another example which shows that less code sometimes may mean less readable code.

Once upon a time...

Today I would like to talk to you about history:
public class History {

public void store(
    Author author, RefactoringType type, Scope scope, 
    RefactoringJustification justification, Date today) {
        // some code
}

Is it easy to figure out what store method is storing? Is it possible to understand? Well, even if it is, I believe that we all may agree that it is definitely hard.

How do you extract necessary information from the method’s declaration? I can assume that firstly you read the class and method names to find the context. Good, we have it. We want to store some historical information. Now the hard part starts - you have to find out what we want to store. You cannot just simply read this information, because it is not present in the code. In that case you will probably try to find this piece of information by looking at the list of parameters. You will read them with the hope that you will be able to figure out what the author of the code wanted to store.
Or you may look at the message of the commit that introduced this code.
Or you may look into the method’s definition and look for the answer in the implementation.
Not the best ideas, though.

Don’t you think that it would be great to have this information easily accessible? To have code we could understand without making an additional effort? I believe this is exactly the way how we should write it.

Parameter Object for the rescue

Why do we not know everything just after reading the method’s declaration?
Somehow we were able to find out there’s something about history in here - the name of the class gives us this information.
We know that it is about storing something - the name of the method is pretty descriptive.
The problem is that we don’t know what we want to store in the history. Why? Because input parameters are not giving us this information.
Those parameters indicate what pieces we want to store, yet, do not explain what we should know when all of those pieces will be put together. We are getting information about implementation (parts that are used) and we have no clue what this code is supposed to do.

What we could do? We should hide implementation and explain what we want to achieve with this code. And that’s the moment when Parameter Object comes to rescue. You may treat it as a box for a few different objects, as a solution that may decrease dependencies. However, for me, the biggest benefit of using this pattern is the fact you will have to name this object and by doing so you will be forced to provide valuable information.
Let me show you:
public class History {

public void store(CodeDelta delta) {
    // some code
}

Now it is obvious what we want to store. We share useful information with the people reading our code. We also hide an implementation. They can focus on things that are important and won’t be bothered by all those additional details that are interesting only when you are writing or modifying the method.

So, what you say, the less or the more is the better?


No comments:

Post a Comment