We love open source at Infi. But that mainly meant using it so far. We want to do more, and the first step towards doing more means knowing more first. So we decided to carefully study a few prominent open source codebases, to see "how they do things". This is what the series will look like:
- Part 1: Dapper.NET
- Part 2: Nodatime (this post)
- Part 3: JSON.NET
This post is about our findings from the Nodatime codebase. Let's dive in!
Time sucks. You know it, and I know it. It forces us to feel insecure about wrinkles and makes us wonder (or wage war) about what happens in the hereafter. The biggest problem of all though, is that programmers have to take into account different time zones and calendars which makes their job frustrating.
Thankfully in our world we have pioneers like Jon Skeet who throw themselves at this abomination of nature so that we can deal with it when creating our own applications.
Nodatime is an extensive library for .NET that tries to fit all your needs when it comes to dealing with moments in time. It helps you to correctly define a specific moment in time. It deals with all different sovereign entities that existed with their own unique time zones and it even allows you to map a date on the Gregorian calender to the Hebrew one. If you had not heard of Nodatime before I would very much recommend checking it out. By arming yourself against problems that are caused by time, you will save yourself a lot of it!
Within the community Nodatime is a well established brand: it has been downloaded over 2.5 million times from NuGet and has an average of a 1000 downloads every day. The legend Jon Skeet is working on improving the library to this instant. For some good examples of a use case of Nodatime, see the User Guide on the website.
Diving into the project
The set goal for Infi's bookclub is to investigate open source projects such as Nodatime. What I loved right away was the ease in which I was able to get things up and running; especially in comparison to other projects we saw.
Unfortunately we were unable to get the unit tests working within Visual Studio.
However, since Jon Skeet decided to put his tests within a Console Application (as opposed to a class library), we were able to just run the tests by executing
dotnet run in the test project directory.
An impressive 17890 unit tests passed.
This was the first time I saw the use of
TestCase's rather than just a large amount of
I'm glad to have picked this up from this experience.
The structure of the solution was rather flat like we saw in other open source (library) projects. A lot of types are simply put in the top level namespace. This allows a lot of type exposure when including the Nodatime namespace in your project. Whether or not this is the reason for structuring the solution as such, we find it to be an interesting pattern across projects.
The code itself is easy to get into.
Jon Skeet is very clinical about his use of conventions in his code which makes everything very readable.
Pretty much every class and every property and every method has an extensive summary that leaves nothing to be assumed.
There is this use of an attribute that is called
SpecialNullHandling that marks a property as one that is not properly null checked.
The attribute itself does not execute any code, but it gives some information on how the marked parameter is used.
What put a smile on my face is the fact that there exists a unit test that fails if there exist
SpecialNullHandling attributes on parameters that are value types (which should not be the case).
It showed me the level of commitment Jon Skeet has to follow his conventions.
The only thing that raised my eyebrows somewhat was the use of constants in some
if statements that were not stored in a variable.
The use of named variables is of course a good way to make explicit the semantic value of what the constant represents.
Throughout the code this doesn't happen often and it would not surprise me if I'm missing some obvious reason as to why it would not make sense to do what I suggest.
A cool outcome of our Bookclub would be an actual contribution to a real world open source project. Unfortunately, similar to the other projects we saw, getting into Nodatime seems much more difficult than what we expected before seeing any open source project.
What makes getting into Nodatime even harder, is that you need to acquire some advanced knowledge on time zones and calendars.
Of course there are parts of the code that are easier to get into, however actually building on a feature in NodaTime seemed really ambitious.
Thankfully my colleague Jeroen (who is also in the book club) was able get a pull request merged which updated the
It feels really good that someone in our group was able to make some impact at least.
This was our second session for the Codebase Book Club. I had never really looked into what revolves around contributing to a project before, but I always had an interest in taking part. If you are like me in that respect, I would definitely recommend committing to such a sequence of investigations of open source projects. I feel like I am now more ready to join in on the fun.