.NET DateTime coding best practices
Author:  Dan Rogers (danro), Microsoft Corporation

January 9, 2004

Synopsis
Writing programs that store, perform calculations and serialize time values using the .NET DateTime type requires an awareness of the different issues associated with time representations available in the Windows and .NET platform.  This article focuses on key testing and development scenarios involving time, and defines the best practice recommendations for writing programs that use the DateTime type in .NET applications and assemblies.

Background
Many programmers encounter assignments that require them to accurately store and process data that containing date and time information.  On first glance, the CLR DateTime data type appears to be perfect for these tasks.  It isn’t uncommon, however, for programmers, but more likely testers to encounter cases where a program simply loses track of correct time values.  This article focuses on the testing issues associated with logic involving DateTime, and in doing so, uncovers best practices for writing programs that capture, store, retrieve and transmit DateTime information.

What is a DateTime, anyway?
When we look at the documentation found in the .NET Framework class library documentation, we see that “the CLR System.DateTime value type represents dates and times ranging from 12:00:00 midnight, January 1, 0001 AD to 11:59:59 PM, December 31 9999 AD.”  Reading further we learn, unsurprisingly, that a DateTime value represents an instant at a point in time, and that a common practice is to record point in time values in Coordinated Universal Time (UCT) – more commonly known as Greenwich Mean Time (GMT).

At first glance, then, a programmer discovers that a DateTime type is pretty good at storing time values that are likely to be encountered in current-day programming problems such as business applications.  With this confidence, many an unsuspecting programmer begins coding, confident that they can learn as much as they need to about time as they go forward.  This “learn as you go” approach can get you into a few snags, so let’s start nailing them down.  They range from issues in the documentation to behaviors that need to be factored into your program designs.

The V1.0 and 1.1 documentation for System.DateTime makes a few generalizations that can throw the unsuspecting programmer off track.  For instance, the docs currently still say that the methods and properties found on the DateTime class always use the assumption that the value represents the local machine local time zone when making calculations or comparisons.  This generalization turns out to be untrue because there are certain types of Date and Time calculations that assume GMT, and others that assume a local time zone view.   These areas are pointed out later in this article. 

So, let’s get started by exploring the DateTime type by outlining a series of rules and best practices that can help you get your code functioning correctly the first time around.

The Rules:

1.      Calculations and comparisons of DateTime instances are only meaningful when the instances being compared or used are representations of points in time from the same time-zone perspective.

2.      A developer is responsible for keeping track of time-zone information associated with a DateTime value via some external mechanism.  Typically this is accomplished by defining another field or variable that you use to record time-zone information when you store a DateTime value type.  This approach (storing the time-zone sense along side the DateTime value) is the most accurate and allows different developers at different points in a programs life-cycle to always have a clear understanding of the meaning of a DateTime value.