Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
3  
make the charging function addCharge easy and clear enough –  ratchet freak Jan 25 '13 at 19:47
2  
Could you prefix the noun variable with "Current-"? So "CurrentCharge" vs "Charge()"? –  Brian Snow Jan 25 '13 at 19:53
6  
or just ChargeLevel to get the current charge –  ratchet freak Jan 25 '13 at 20:27
5  
Make up a word. WordNet doesn't think enqueue is a word, but its a verb in Java. How about doCharge? It will still fail symmetry test because your other methods will not have this prefix –  Miserable Variable Jan 25 '13 at 20:38
5  
"Current" = now, or "current" = flow of charge. The only real solution is to replace English with a more sensible language! –  DarenW Jan 26 '13 at 3:26

7 Answers 7

up vote 32 down vote accepted

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.

share|improve this answer
1  
Excellent point on the units. Units are explicitly left off in this case because they can change depending upon the analysis we're running. Ie, we're using different time scales and the Battery adjusts its operations in terms of the analysis' scale. –  GlenH7 Jan 25 '13 at 20:10
4  
+1 for nouns of non-mutating functions. –  Mathew Foscarini Jan 26 '13 at 19:15
1  
I prefer verbs for expensive, non-mutating functions. E.g., functions that run a query on a database. –  Brian Mar 8 '13 at 21:55

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.

share|improve this answer
    
+1 for the unique perspective on the answer. Regrettably, Hungarian notation is explicitly verboten per our code style guidelines. That doesn't change the potential merit of your answer, just that I can't use it as my actual solution. –  GlenH7 Jan 25 '13 at 21:58

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.

share|improve this answer
6  
It's not a bad thought, but in this case Battery is an abstraction for the battery + charging system. Our app doesn't require breaking the two aspects out into separate objects, so they are rolled into one (aka Battery) for convenience. Ultimately, the physics of a chargeable battery dictate that it has some sort of function to accept a charge. –  GlenH7 Jan 27 '13 at 1:12
    
In that case, I submit that kevin cline's answer is what you are looking for. For clarity, I would use Recharge and Discharge for the mutating functions and Charge for the property name. Perhaps ChargePercent would be a good one as well. –  mortalapeman Jan 27 '13 at 2:02
    
Are you perhaps a Java programmer? This is clearly a violation of Don't Repeat Yourself. In fact, you're repeating EVERYTHING except the parameter "50". I couldn't come up with a worse example of a DRY violation if I tried. –  boxed Mar 11 '13 at 8:47
    
@boxed Are you taking about my example? Because I am not sure how you can claim I am violating DRY when I have no implementation. I am a huge proponent of SOLID principles and am just not seeing how you came to that conclusion. –  mortalapeman Mar 11 '13 at 16:08
    
You are violating DRY by creating an unnecessary BatteryCharger class that will somehow then cause a state change in the Battery. So BatteryCharger will accept some input that it will then immediately pass on to Battery. –  kevin cline Mar 13 '13 at 20:08

Prepend them with verbs that will make them a verb or a noun.

Battery.doCharge()

Battery.getCharge()
share|improve this answer

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.

share|improve this answer
2  
For the record, the client is the one who is using the ambiguous terminology. I didn't create that mess. :-) I brought the question up since I thought I may not be the only person walking into such a situation. You have some valid points in your answer. In this particular case, we're not working at the granularity of time that StartCharge() and EndCharge() would imply. In fact, that terminology would add significant overhead to handling the battery system. At each interval it can either Charge() or Discharge(). –  GlenH7 Jan 27 '13 at 1:19
1  
The primary struggle is in keeping internal programming semantics synchronous with the terminology that the client is using. Charge happens to be the most readily understood ambiguous word for this domain. There are several others. –  GlenH7 Jan 27 '13 at 1:20

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).

share|improve this answer

For the verb case, I think Charge is OK. For the noun case, would getCurrentChargeLevel work for you?

share|improve this answer
    
Not sure on that. Since we're using C#, we can declare the get and set on the Property instead of needing separate functions. Irrespective of that, I'm concerned about maintenance and how it will look once I've forgotten what I wrote. Wouldn't getCurrentChargeLevel() would still need to refer to an internal variable of Battery, and what would the name of that variable be? –  GlenH7 Jan 25 '13 at 19:49
    
is charge a voltage or a percentage? –  mhoran_psprep Jan 25 '13 at 19:52
1  
@GlenH7: Ah, I see. You didn't specify C# and my brain is in Java mode. Well either way, I think that for the noun representing the amount of charge currently in the battery, something along the lines of Battery.currentChargeLevel might work. You could try using Battery.coloumbs or Battery.ampereHours but that might not be as obvious... –  FrustratedWithFormsDesigner Jan 25 '13 at 19:59
1  
@mhoran_psprep - neither. ;-) Charge is Energy which is Power (Volts * Amps == Watts) multiplied by time. So in this case, charge is a number. There is also a state of charge which happens to be a percent. –  GlenH7 Jan 25 '13 at 20:03
    
@FrustratedWithFormsDesigner - yes, I left C# out since I thought the broader corner case was applicable regardless of language. Watt*time definitely wouldn't align with design conversations, but ChargeLevel would. –  GlenH7 Jan 25 '13 at 20:05

protected by Yannis Rizos Jan 31 '13 at 21:25

Thank you for your interest in this question. Because it has attracted low-quality answers, posting an answer now requires 10 reputation on this site.

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.