Putting units in identifiers?

[Guest]

I just saw an interesting identifier in a C# book I'm reading...

double dollarsPerHead

This jumped out at me, as it is not common to put units in an identifer. We
don't see "millisecondsSinceStart" ("time"), or "milesPerHour" ("speed").
But, perhaps it's a good idea. If memory serves me right, one of the Mars
landers crashed because two development teams used different units (metric
and imperial), across an interface. Also, when I'm coding, I'm frequenctly
checking units against specs, when it would be easier just to read the
identifier.

I think that a project should be consistent -either always include the
units, or never include them.

My opinion - if the unit is included, then programmers will trust the
identifier, rather than specs, and if the unit ever changes, but the
identifier doesn't, then the identifier is misleading. Therefore, units
should never be included in identifiers. My general approach to "conventions"
is to avoid conventions which can't be enforced automatically.

So I would replace "dollarsPerHead" with "ticketPrice"

Opinions?

Javaman.

oh, the book is "Design Patterns in C#", by Steve Metsker. I highly
recommend it.

 

[Bruce Wood]

I agree, if you're going to pass quantities around as ints, decimals,
or doubles, for example.

I solved the problem a different way: I created the following:

a UnitOfMeasure class that encapsulates the "unit of measure" concept:
minutes, pounds, feet, sqaure meters, etc.

a Measure structure that encapsulates a value and a unit of measure.

a PricePerUnit structure that encapsulates a value, a currency, and a
unit of measure.

Originally I envisoned a very rich, complex system that would support
arbitrary combinations of units of measure and allow multiplication and
division operations on them, but it turned out we didn't need anything
that sophisticated here. It was enough to be able to automatically
convert between feet, inches, millimeters, and other such units, so I
came up with a conversion class to handle standard conversions, and I
was done.

I encourage everyone in our group to return Measures, not decimals or
ints. That way the UoM follows the value around wherever it goes.

However, if we were to just pass basic types, I would insist on
including units in names. Few things suck worse that finding a value in
some far-flung corner of the system and having no idea in which units
its expressed. (Recent example: a column in our database mistakenly
labeled "SPECIFIC_GRAVITY" that really contained pounds per (foot times
square millimeters). Don't ask.)

 

[Jon Skeet [C# MVP]]

I just saw an interesting identifier in a C# book I'm reading...

double dollarsPerHead

This jumped out at me, as it is not common to put units in an identifer. We
don't see "millisecondsSinceStart" ("time"), or "milesPerHour" ("speed").
But, perhaps it's a good idea. If memory serves me right, one of the Mars
landers crashed because two development teams used different units (metric
and imperial), across an interface. Also, when I'm coding, I'm frequenctly
checking units against specs, when it would be easier just to read the
identifier.

I think that a project should be consistent -either always include the
units, or never include them.

My opinion - if the unit is included, then programmers will trust the
identifier, rather than specs, and if the unit ever changes, but the
identifier doesn't, then the identifier is misleading. Therefore, units
should never be included in identifiers. My general approach to "conventions"
is to avoid conventions which can't be enforced automatically.

So I would replace "dollarsPerHead" with "ticketPrice"

The problem is that if you're implicitly saying that if the unit isn't
included, then programmers will consult the spec. That's not my
experience.

I've only recently started including units, particularly for timing -
things like:
void DoSomething (int timeoutSeconds)

and also, while not strictly a unit:
void DoSomething (DateTime timeUtc)

It's made things a lot easier so far.

Note that if you're changing the spec, then the identifier is only one
change - and a very easy one at that. I would say there's far more risk
from identifying all the places it's used, and changing those
accordingly. Where a property name includes the units/timezone, this is
actually made a lot easier: you can change the name to indicate the new
unit/timezone, and that will be a breaking change - you can find all
the uses just by trying to build again

Jon

 

[Bruce Wood]

To clarify, when I said "I agree" I meant that I was agreeing with the
idea of including units in names if you're not going to create a
Measure structure. Consider the following lines of code:

decimal speed = 17.5;
decimal length = 20.5;

How fast is that? How long is that? You have no idea. Whether those are
variables, parameters to methods, or properties, the same problem comes
up: the numbers are meaningless. Compare that with this:

decimal speedKph = 17.5;
decimal lengthFeet = 20.5;

Now you know exactly what the numbers mean. In our system, we take it a
step farther and do something like this:

Measure length = new Measure(20.5, UnitOfMeasure.Feet);

Now we can pass "length" around as a Measure, and any part of the
system can unpack it and see exactly how long it is. In particular, we
can do this:

if (length < new Measure(10, UnitOfMeasure.Inches) || length > new
Measure(20, UnitOfMeasure.Feet))

which in our industry is valuable indeed.

Putting units in variable names makes values meaningful to the
programmer. Creating a structure that contains units and a quantity
makes values meaningful to the code.

 

[Guest]

Thankyou both for your excellent replies.

I like Bruce's proposal for a Measure class and PricePerUnit class. There is
some overhead, but it could save time on a medium to large projects, and it
is re-usable between projects.

I agree with both of you that in the absence of a Measure class, then we
should put units in our identifiers.

These proposals are especially helpful for software teams, but scale down
well also. Even in my currrent project (1 man year), I find that I keep
forgetting the unit of measure on variables (nanoseconds? milliseconds?..),
and either waste time looking it up, or take a guess, and hope for the best.


Regards,

Javaman

 

[Bruce Wood]

I like Bruce's proposal for a Measure class and PricePerUnit class.

You'll find that it will work better if you make them structs, and make
UnitOfMeasure an immutable class.

Just thought I'd save you some grief.

 

[Eric NY]

There is now a robust java solution I've been reading about called jscience
(http://jscience.org). Is anyone aware of a similar effort in the .net
community?

I'm in need of a few quantity types to deal with some common dimensions of
measurement in business, with Money being at the top of the list, and Time &
Length following. I'd rather focus on the domain issues than creating this
deceptively complex support structure. Any links to code samples that do this
would be much appreciated.

Bruce, you sound like you've spent a bit of time on this already - do you
have code you're willing to share?

TIA
Eric