Question

Of the following two options for method parameter names that have a unit as well as a value, which do you prefer and why? (I’ve used Java syntax, but my question would apply to most languages.)

public void move(int length)

or

public void move(int lengthInMetres)

Option (1) would seem to be sufficient, but I find that when I’m coding/typing, my IDE can indicate to me I need a length value, but I typically have to break stride and look up the method’s doco to determine the units, so that I pass in the correct value (and not kilometres instead of metres for example). This can be an annoying interruption to a thought process. Option (2) alleviates this problem, but can be verbose, particularly if your unit is metresPerSecondSquared or some such. Which do you think is the best?

Answer 1

I would recommend making your parameter (and method) names as clear as possible, even if they become wordy. You’ll be glad when you look at or use the code in 6 months time, or when someone else has to look at your code.
If you think the names are becoming too long, consider rewording them. In your example you could use parameter name int Metres that would probably be clear enough. Consider changing the method name, eg public void moveMetres(int length).

In Visual Studio, the XML comments generated when you enter 3 comment symbols above a method definition will appear in Intellisense hints when you use the method in other locations. Other IDEs may have similar functionality.

Abbreviations should be used sparingly. If absolutely necessary only use commonly known and/or relevant industry-standard abbreviations and be consistent, ie use the same abbreviation everywhere.

Take a step back. Write the code then move on to something else. Come back the next day and check to see if the names are still clear.

Peer reviews can help too. Ask someone who knows the programming language (or just thinks logically), but not the specific functionality, if your naming scheme is clear enough or to help brainstorm alternatives. They might be the poor sap who has to maintain your code in the future!