Order of subject and modifiers in variable names

I’m looking for experiences regarding the ordering of the subject and modifiers in variable names.

A simple object Shape would have just a subject for the variable name, such as Area.

A slightly more complex case Sphere which has a wall will have an inner volume and an outer volume, which is where my question comes into play.

What’s preferred between Modifier-Subject or Subject-Modifier?

As an example set:

class Containers_Modifier_Subject
{
  AreaAdjustmentFactor
  WallThickness
  Height
  Length
  Width
  AdjustedArea
  SurfaceAreaInner
  SurfaceAreaOuter
  LongWallArea
  ShortWallArea
  TopArea
  InnerVolume
  OuterVolume
}

class Containers_Subject_Modifier
{
  AreaAdjustmentFactor
  WallThickness
  Height
  Length
  Width
  AreaAdjusted
  AreaInnerSurface
  AreaOuterSurface
  AreaLongWall
  AreaShortWall
  AreaTop
  VolumeInner
  VolumeOuter
}

The trigger for my question comes from an object that is similar to the examples. There were enough variables in the object that only a portion displays in the code ahead / lookup window from the IDE. I want to make sure that any future developer is quickly led to the correct variable that they’ll be looking for without having to scroll up and down through the lookup window.

In my case, I was looking for the total area, but the area factor and adjusted area values had popped up first.

Consistency in naming as a code standard is a given.

Which naming approach has been:

most maintainable?
more easily understood?
semantically correct?
- i.e. how well does the variable name match the business object and how well does the variable name flow into conversations about the problem being solved?
conducive to being used with code lookup functionality like Intellisense or the various Eclipse based constructs?

You’re thinking along the right lines. Most people prefer names they can read in their head and have it sound close to regular English.

However, the fact that you are having difficulty with long lists in intellisense isn’t a variable naming problem, it’s a class size problem. When you start needing to differentiate by a prefix, that’s a good sign you need to split that prefix off into its own entity somehow. For example, Container.Area[INNER]. Use the features of the language, that’s what they’re there for.

In my API’s I always use names that describe what I expect the user to type: TotalArea instead of AreaTotal, but WallCount instead of CountWall, as the latter examples are improper English.

Using subject-modifier is something designers do only to satisfy IntelliSense, as typing Area would then result in a list of only those things dealing with area – which is nice – but this does not warrant using strange names. A much better option would be to separate the properties of an area into a separate Area object. This makes the API cleaner, the class shorter, and improves reusability and testability. Your example class would then become:

WallThickness
Height
Length
Width
Area
Volume

To conclude: use the word order you’d use when writing it in normal English. If you have multiple such prefixed properties, fields (and methods), consider putting those members together in a related class. This improves maintainability (testability and reusability), allows IntelliSense to suggest only relevant area members after typing Area., and makes the objects match their business objects more closely (in most cases).

And never ever use a particular coding convention only to satisfy your programming envionment (e.g. code completion in Visual Studio or Eclipse).

For what it’s worth, the two factors I give the most value to when naming variables (other than meaning, of course) are

Is it readable, namely how likely is it that I may read it incorrectly or accidentally choose it from an Intellisense list?
How does it sound when spoken? Can I talk about my variables with out confusing myself, getting tongue-tied or sounding like a Dr. Suess book?

So, for those reasons, AdjustedArea is better than AreaAdjusted ( it just sounds more natural)
SurfaceAreaInner and SurfaceAreaOuter are way better than AreaInnerSurface and AreaOuterSurface (where the qualifier is actually hidden in the middle of the name), but I may actually prefer InnerSurfaceArea and OuterSurfaceArea, as that’s how I would refer to these things if I were a civilian, so to speak, and not a developer.

I don’t think there is a single right answer to this question. In fact, it borders on a religious issue ;).

Both subject-modifier and modiier-subject have merit and disadvantages. Some of these are not inherent in the variable names themselves, but in the tools used to create and maintain the code (such a name assist using only starts-with).

Sometimes, the only difference between the two can be your point of reference. For example wallThickness, if I am working with various thicknesses, wall is the modifier. If I am looking at walls, thickness is the modifier.

Probably the best answer is to fit in with your existing code base. To do otherwise would mean that other team members would be surprised by your name choices. This will lead to duplication of computation and a general degradation of coding and maintanence speed.

In a coding standard, I might express a recommendation to prefer one over the other, but I would not make it a hard and fast rule. I would trust the programmers to make the best choice in each particular circumstance.

I think variable naming should support thinking above anything else (be it a commonly known convention or a language syntax). This immediately makes one decision: the SubjectModifier version, because in this way the name expresses the organization of data: PlannedStart, PlannedEnd, PlannedCost; ActualStart, …

I consider supporting IntelliSense not only good, but important! When looking at an unknown code, I don’t care how many getters and setters they have made, but I want to understand what components (Subjects) are there in it, and only then what I can do with them (Modifiers). Feeding IntelliSense properly will surely save other programmers (and perhaps even yourself after a few months) some seconds every time you call a function or refer to a member variable. That quickly accumulates to hours.

… and perhaps something even more important: control. I like narrowing the scope by each letter I type. I prefer typing the subject and getting a list of things that I can do with that subject, to typing “access” and still have to browse among the Subjects… or even then realizing that it was not “access” but “get” for that Subject, because my target Subject is missing from the list. Aaargh…

IntelliSense is there to save you (and fellow programmers) time and let you avoid frustration. If you use it.

Container is another issue, and I agree that when you have a question about a container in your naming system, you really have a question about the class hierarchy. My example is just on the line, but right now I started hesitating whether to create a TaskInfo class with Start, End, Cost fields, and use InfoPlanned, InfoActual in the parent.

Creating such small classes result in a more flexible application. TaskInfo would let me create a TaskInfoPanel displaying Start, End, Cost properly – and I could reuse that panel twice to show Planned and Actual costs. It would also allow having even more TaskInfo instances to the project – like having more estimations made by different persons: offers from different service providers. In the end, this new structure would support a project planning system where you can separate task planning (internal) and execution (internal/contractor), let the contractor make their (perhaps multiple, parallel) offers to some tasks, from which you can choose and build the project planned timeline, make the contract, and so on.

A bunch of viable services just because I decided to extract a meaningful group of data into a separate class… I just played with the idea right now, but the consequence is evident, and when I will meet this scenario, I surely would use this approach.

So, I would strongly suggest you to separate your data into the smallest containers with strictly one responsibility. This allows broader reusability, more flexible structure, narrow interface; and I also think that it is much easier to understand. I think we can easier get the picture of a system having a hierarchy with precisely defined small components than some big, feature-oriented blocks.

My 2 cents.

I prefer modifier-subject because that is how English is usually written and spoken.

If there is a clear specific benefit in a certain situation to make a name subject-modifier, I will.

Filed under: softwareengineering - @ 11:28

Thẻ: coding-style, naming, variables

Thiết kế website giá rẻ

Danh mục

Order of subject and modifiers in variable names