I have run into a corner-case problem with the general guidance of:
- nouns for variables
- verbs for functions
Specifically, I have a case where the word is ambiguous – it can be either a verb or a noun. And in some cases when we’re discussing the application, it will be used both ways in the same sentence.
My intent is to make sure the program will remain readable to future developers as well as myself when I return to sections of code months later.
One of the examples is with a battery
. A battery
has a charge
and you can also charge()
a battery.
I think that having both Battery.Charge
and Battery.Charge(value)
will be confusing to future developers.
My current solution is to simply pick a different word for one or both of those cases (the variable and the function). My problem with that approach is the Battery
object’s variable and function for charge
won’t align with design discussions involving the Battery
.
My question is if there is another / better way to handle this conflict in naming convention?
Some additional reading on the subject. None really addressed the particular of my question.
- Meaningful concise method naming guidelines
- Naming conventions for variables
- The selected answer from https://softwareengineering.stackexchange.com/questions/14169/what-naming-guidelines-do-you-follow
13
In similar situations I try to find synonyms. In this case I would use “recharge” for the verb. The “re-” is slightly redundant, but the meaning is clear. Using the simple “charge” for the remaining charge in the battery is ambiguous because it doesn’t specify any physical units. I would prefer “availableAmpHours”, “hoursUntilRecharge” or something similar. The units will depend on whatever is convenient for the application.
My personal preference is to use verbs only for functions that change state. I use nouns for non-mutating functions. I suppose it depends on your point of view. At the machine level, non-mutating functions do something, but at the model level, they don’t.
3
Just throwing this out there, but maybe the solution for this instance of naming ambiguity is to remove that functionality from the battery entirely. I’ve never seen a self charging battery and it would make more sense to me to have a BatteryCharger class. This would help keep your concerns more decoupled and make the action more explicit.
battery.Charge(50)
vs batteryCharger.Charge(battery, 50)
To me, the second form is much more understandable and keeps all your “Charging” code in one place rather than sprinkling it throughout all your battery classes.
6
Avoid Double Meanings
You have deliberately selected a word that has more then one meaning, and that first decision is the problem. There are a ton of words that are problematic for programmers. Another example would be phone
. You can phone
someone, or you could have a phone
in your pocket.
Use Getters and Setters
The standard naming for most objects is the getters/settings methods for properties.
Battery.Charge // would be a property
Battery.setCharge(value) // would set the property
Battery.getCharge() // would get the property
Properties Are States Not Nouns
I think you are mistaken by classifying object properties as nouns, and variables could also be thought of states. They are states relevant to the local scope of their existence.
You could describe the value that they hold as a noun, but I’m not sure that is true in all cases.
In OOP terminology object properties describe the state of that object. In your case the Battery
is an object, and it’s Charge
is a state. So that would be a property of the object, but this depends on the context of how it’s used.
If you need to be able to Charge
the battery, and also know what it’s current Charge
is, then you have a problem.
Using Scope To Enforce Context
Context is what will clarify which meaning of a word you intend a method or property to convey. Scope is setting the accessibility of a property/method from outside the object.
Batter._charge // a hidden private property
Battery.setCharge(value) // would set the private property
Battery.getCharge() // would get the private property
Battery.Charge() // would perform the Charge action
Methods Are Verbs
You can describe the method of an object as a verb, but the word action is better suited. In OOP terminology you perform actions upon objects using their methods. It’s bad form to modify an object’s property from outside the object. It’s preferred to call a method that performs the actions required that causes it’s state to change.
The word Charge
is a verb, but it’s also a noun. When used to call the method of an action it becomes clear that the verb is being used Battery.Charge(....)
.
But, context is very important. While the word Charge()
is a verb it’s not as meaningful as startCharging()
.
Valid methods for Battery
could include Charging
, Discharging
, setCharge
, getCharge
, hasCharge
, Discharge
and Charged
.
Simple one word methods often don’t explicitly state their actions clearly, but there are some cases like open
and close
where little explaining is required.
So there isn’t really a correct answer as to how to name these types of properties/methods. Except that you need to use the above techniques wisely to ensure there is no confusion.
2
Prepend them with verbs that will make them a verb or a noun.
Battery.doCharge()
Battery.getCharge()
For the verb case, I think Charge
is OK. For the noun case, would getCurrentChargeLevel
work for you?
5
In most cases adding a helping verb, adverb, or adjective is good enough to distinguish them and can actually help with understanding. With your case of Charge and Charge() on a battery making it DeltaCharge() could show that it’s a function that can handle either charging or discharging.
Delta (in cases where there’s a change but ambiguous) is a modifier that I use and recommend to others all the time for handing change in state (even if the verb is semi-obvious).
Hungarian Notation to the rescue. You can have intCharge
and fcnCharge(value)
, thus avoiding confusion and not adding a crazy long name when three letters will work just fine.
Or you could just use the same name and let the IDE handle it. Creating a longer or different name may be just as confusing in the long run anyway.
1
How about a coding convention for fields?
// C++
class Battery
{
private:
T _charge{}; // or m_charge or charge_
public:
charge( Time length, Current max_current );
}
You need different words for both meanings of “charge”. StartCharging and ChargeLevel will do. If you change only one word, someone will call Charge() when they actually wanted to call the other one.