Suggested parameter names for utility class function During our internal code review process, my following code raised some eyebrows:

public class MySuperUtil {
    public static List&lt;Long&gt; updateAndSubtract(List&lt;Long&gt; first, List&lt;Long&gt; second) {
        List&lt;Long&gt; updated = updatePlaceholdersWithLargestIds(second, first);
        Collection&lt;?&gt; difference = CollectionUtils.subtract(first, updated);
        return castCollectionToListUsingClass(difference, Long.class);
    }


(the castCollectionToListUsingClass is not related to this problem; it is from this SO answer)

The main feedback is the names of parameters: first and second.

My reviewer suggests using names more informative to the caller, e.g. inDB instead of first, inUI instead of second.

My main points (of using first and second) are:


this is a Util class (although probably there will be only one occasion for it to be used) 
this is similar to what CollectionUtils.substract() has


I guess my question really is: 
what context do we use when naming those two parameters?


do we name them in the context of the callee MySuperUtil (thus 
something like first and second, or probably minuend and subtrahend), OR, 
do we name them in the context of the caller (thus inDB and inUI)?


Any suggestion is appreciated.
public class MySuperUtil {
    public static List&lt;Long&gt; updateAndSubtract(List&lt;Long&gt; first, List&lt;Long&gt; second) {
        List&lt;Long&gt; updated = updatePlaceholdersWithLargestIds(second, first);
        Collection&lt;?&gt; difference = CollectionUtils.subtract(first, updated);
        return castCollectionToListUsingClass(difference, Long.class);
    }



My assessment of the code is that, as a Util method, it is poorly named too. The methods are not self-documenting.

I read updatePlaceholdersWithLargestIds, and with two lists as inputs, where is the Id? What does 'updated' look like? I am at a loss.

What I can say is that there is some black-box function that does some update, but, does it manipulate the data in first, or second? Why is 'second' specified first? Why is it not: updatePlaceholdersWithLargestIds(first, second);

Also, why does an update* function return a value, and not update something? it should be called get* or just largestIds. Or, does the function do both? Does it update values and also return values? Yuck!.

The subtract function. Does it subtract the first value from the second, or the other way around?

castCollectionToListUsingClass I presume this method has the signature:

public static &lt;U&gt; List&lt;U&gt; castCollectionToListUsingClass(Collection&lt;?&gt; collection, Class&lt;U&gt; clazz);


Why all the redundancy? That method name duplicates all the signature components. It is tautology. Also, why does it take a collection, and return a List? It should return a Collection too, or it should be parameterized too.... at minimum, just rename the method to something like (I like the word coerce):

public static &lt;U&gt; List&lt;U&gt; coerceMembers(Collection&lt;?&gt; collection, Class&lt;U&gt; clazz);


So, I would agree that naming is a concern in your code, but it extends beyond just your method.

Your method does not tell me what it does, and the code in the method does not help much either. The code in the method does not help me help you rename the method.