Naming things isn’t hard: if it contains a number, include the unit in the name (your timeout might not be in nanoseconds)
Posted by jpluimers on 2025/05/27
This case, it was C# accessing a SQL back-end, but the responses to the Tweet how so many more examples not even related to software development.
Remember that plane crashing because they overloaded while they thought the fuel load numbers were in Imperial pounds where in fact they were in metric kilograms?
That’s why naming things that contain numbers should contain the unit in their name!
Related blog post: Watch “Felienne Hermans: How patterns in variable names can make code easier to read” on YouTube
Tweet: [Wayback/Archive] Nick Craver on Twitter: “Troubleshooting a hanging test suite and godDAMMIT. “In seconds”. Integer timeouts should be a felony offense punishable by an indeterminate amount of seconds/milliseconds/hours/fortnights/whatever the judge chooses.”
var csb = new SqlConnectionStringBuilder(TestConfig.Current. SQLServerConnectionString) { ConnectTimeout = 2000 }; int SqlConnectionStringBuilder.ConnectTimeout { get; set; } Gets or sets the length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error. Returns: The value of the SqlConnectionStringBuilder, ConnectTimeout property, or 15 seconds if no value has been supplied.
You do not have to reinvent the wheel on this: there are plenty of interesting places where you can find information on appropriatie naming or other solutions.
What you do have to, is being aware of these situations and feel an intrinsic need to solve them instead of taking an easy way out like this:
[Wayback/Archive] Rock Avenger on Twitter: “@Nick_Craver The documentation specifies seconds so… hover over and find out when in doubt (rhyme not intended)”
In this particular case, instead of using a more appropriate name, one could also change the data type to be more appropriate, like a specific timespan. Many software development stacks offer that. It allows to use various units as input.
Naming in documentation and correspondence is just as important as naming in software. A good reading that respect is [Wayback] Proefschrift_van_Blommestein.pdf (Structured communication for dynamic business an architecture for flexible B2B communication, Fred van Blommestein).
On the documentation side, Wikipedia has a great page Wikipedia:Manual of Style/Dates and numbers – Wikipedia where you should at lease read these sections:
- Wikipedia:Manual of Style/Dates and numbers: Units of measurement – Wikipedia
- Wikipedia:Manual of Style/Dates and numbers: Chronological items – Wikipedia
An interesting time drain is [Wayback/Archive] “Unit mismatches” – Google Search.
When unit mismatches cause real harm (its not just Imperial vs Metric, also weeks versus months, color model (RYB versus RGB versus BGR versus RBG), dozen versus tens, day/month versus month/day, etc):
- Gimli Glider – Wikipedia:
The accident is commonly blamed on mistaking pounds for kilograms, which resulted in the aircraft carrying only 45% of its required fuel load.
- Mars Climate Orbiter – Wikipedia
An investigation attributed the failure to a measurement mismatch between two software systems: metric units by NASA and US customary units by spacecraft builder Lockheed Martin.
This is why I wrote the blog post: [Wayback/Archive] Jeroen Wiert Pluimers @wiert@mastodon.social on Twitter: “@Nick_Craver This is the standard example I show when teaching people about naming identifiers. When an identifier refers to a measurable entity, always include the unit as part of the identifier name.”
I have been teaching this for a long time, but forgot to post about it (:
Oh, and try to stick to metric units unless Imperial is really appropriate. Time to once and for all end the Wikipedia:Measurements Debate – Wikipedia
- In Canada and the UK, the only non-metric units are for drinking and driving. There’s something poetic about that.
--jeroen
The Wiert Corner - irregular stream of stuff 
Leave a comment