Good naming convention for functions and methods which may modify (write back to) a parameter.

Question

Hello, everyone!

I need to find a good and understandable naming-scheme for routines which deal with "value arrays" (I've written something similar to C++'s valarray in Java, with some optimizations for primitive types in mind).

I know that the main categorization of routines is made between:

• functions (they may take parameters and must return something)
• methods (they may take parameters and don't return anything)

For performance reasons, I allow to define not only functions/methods which threat their parameters as readonly, but also functions/methods which may modify their first parameter.

So that one can not only do this... :

ValArrayInt a=..., b=...;
// "apply" treats "a" and "b" as readonly
ValArrayInt temp = ValArrays.apply(adder, a, b); // temp = a + b
a = temp;

... but also this:

ValArrayInt a=..., b=...;
// "apply" modifies "a"
a.apply(adder, b); // a += b

Please, suggest a naming scheme for these kinds of routines:

• functions which treat all parameters as readonly
• functions which may modify their first parameter
• methods which treat all parameters as readonly
• methods which may modify their first parameter

I have thought of something like ModifyingMethod, NonModifyingMethod, or similar, but I think those names are not straightforward enough, and too long.

Answer 1

It may be complex to encode this info into the method name.

On the other hand this info must exist on the documentation of the method (e.g on the Javadoc) by explicitly stating the sideeffects of the method.

Answer 2

I always use the word "update" in a method name to indicate that one or more of the parameters will be updated as a result. For ex:

updateClaimWithPolicyDetails(Claim c, PolicyCriteria pc, String identifier)

You can reasonably deduce that this method might update the Claim object. Then if a user wants to know more he can dig into the javadoc

For functions that return something and also update parameters something like "updateAndGet" could be used.

public Policy updateClaimAndGetPolicy(Claim c, PolicyCriteria pc, String identifier) 

From this you can deduce that one is updating the Claim and returning a policy (the claim may be already updated for the policy).

If the word updateXXX is not used in a method then you should assume that all params are readonly. If you have two updatable parameters then you could say

updateClaimAndPolicyCriteria(Claim C, PolicyCriteria pc, String junkParam)

The above can tell you that both claim and policy criteria will be updated.

Answer 3

I like the above answer of pre-pending update or modify. However, this should really be a function of documentation to describe what calling a function does and how it affects the parameters. However, usually you don't want to modify parameters passed to a function, thought there are cases (like Collections.sort) where you want to do this to prevent a copy. Also, make sure to use immutable objects where appropriate instead of always using some stupid java bean class with all public getters and setters.