Huh? We’re waiting how long?
You don't have to work for a long time in software development to come across code similar to the following
void DoSomething()
{
var data = GetData(5000);
}
Data GetData(int timeout)
{
Thread.Sleep(timeout); // or something that takes a while
}
There is one major issue with this code that specifically relates to its readability and consequently its long term maintainability.
Can you spot it?
Don’t worry if you couldn’t. This is a very easy flaw to miss and is usually not uncovered until someone is tasked with maintaining or changing a block of code like this.
What is a “timeout”
The issue with the code block above is that the unit of the “timeout” value is unclear at the point of use.5000 of what? Seconds, micro-, milli-, nano-, cpu ticks? *gasp* maybe it’s minutes! You just can’t be sure unless you check.
This one coding issue has in the past caused me to loose countless minutes in extreme code deep-diving and wading through disassembled code just to figure out exactly what unit is being implied for “timeout”.
Issues such as these can also cause more subtle and hard to track down issues related to unit mismatches as the code is extended or used by other programmers. What if one programmer is expecting milliseconds but others supply microseconds? Sometimes these issues cause multi-million dollar losses as was the case with the Mars Climate Orbiter in 1999.
For every problem there is a solution
Here are three simple alternatives that can help you avoid making or mitigate this kind of an issue and significantly improve your and your colleagues life’s in the long run.The code examples below are presented in C# but apply to most modern programming languages.
Solution 1: Working under tight constraints
By simply tagging the relative function and parameter names with the explicit timeout unit a lot of uncertainty has been removed. If changing the function name is impossible due to legacy constraints, just changing the parameter name to reflect the unit will help immensely and can usually be done without sacrificing any backwards compatibility (exceptions to this are when relying on named parameters).void CoolAndClear()
{
var data = GetDataWithTimeoutMSec(5000);
}
Data GetDataWithTimeoutMSec(int timeoutInMilliseconds)
{
Thread.Sleep(timeoutInMilliseconds);
}
Solution 2: Having full freedom to change
The absolute best case scenario is when you’re able to modify the parameter type to be a non-ambiguous type. An example of this would be to change the timeout variable’s type from int to a System.TimeSpan struct instead.void CoolAndClear()
{
var data = GetData(TimeSpan.FromMilliSeconds(5000));
}
Data GetData(TimeSpan timeout)
{
Thread.Sleep(timeout);
}
In this case the exact unit is explicitly stated at the point of use and all ambiguity is removed. This also provides solutions for special cases such as when specifying an Infinite timeout value or special hard-coded custom values.
Note that it would not be advisable to mix both Solutions 1 and 2. Their combination would introduce even more ambiguity than before. Such as this statement
GetDataWithTimeoutMsec( TimeSpan.FromMinutes(10) )
Solution 2: Extra credit
When using the System.TimeSpan or other custom object there exists the possibility in C# to create extension methods to make the code even more concise and simpler to readvoid CoolAndClear()
{
var data = GetData(5000.MilliSeconds());
// or
var data = GetData(20.Seconds());
// or
var data = GetData(3.Minutes());
}
If you like this approach then feel free to download the skeleton code for these extension methods from my OneDrive.
Solution 3: Working under impossible constraints
In some cases you might find yourself working under almost impossible constraints where modifying any part of the code is not permitted. In those cases adding clear documentation would still be a huge improvement.void CoolStuff()
{
var data = GetData(5000);
}
/// <summary>
/// Gets data with a user supplied
/// <see cref=”timeout”/> in milliseconds.
/// </summary>
/// <param name=”timeout”>The timeout value in milliseconds.
/// Value of 0 will cause the function to return immediately.
/// Value of -1 will specify an infinite waiting period.</param>
Data GetData(int timeout)
{
Thread.Sleep(timeout); // or something that takes a while
}
Actually come to think of it, even if you end up choosing to do either solution 1 or 2, always do Solution 3 as well.
. . .
This entry can also be found on Medium:
https://medium.com/@sverrirs/timeouts-and-timespans-ca05ae5c2d15#.usxppi1h8
Update 4 Feb 2016 There is a more 
The