Let's skin the proverbial cat by breaking out the title
A money value-object
In this context "money" refers to a quantity that represents a mean of payment in an accepted currency. That is, a monetary quantity is made up of an "amount" that makes sense in the context of a given currency.
Remove the quantity of "five dollars" and saying you have "dollars" won't get you far when buying a car.
Likewise, remove the currency and the number alone makes little or no sense when declaring your wealth.
According to Martin Fowler (author of the highly recommendable Patterns of Enterprise Application Architecture, a Value object is:
A small simple object whose equality isn't based on identity
Which is to say two value objects are equal is their values are equal.
A money value-object is, thus, a small (most likely immutable) type that represents a monetary quantity by specifying its amount and its currency and that allows meaningful and correct operations between instances.
Why do we need a money value-object in .NET?
Short answer is because there is none.
Sufferers of primitive obsession might use raw numbers for formatting. It is unfortunate that such capabilities are mixed up with interesting and complex stuff such as languages, cultures, regions, calendars,...
Using a raw numeric primitive and relying on cultural context might lead to dangerous misunderstandings: is this number in dollars, euros or is it the length of some random king's arm? And that is obviating the fact that a perfectly valid operation between two numbers, such as sum them up, might be totally incorrect as-is between two monetary quantities if they happen to be in different currencies.
We can discipline our way around with numbers, format providers and good naming but reality is, we are way better off encapsulating money rules and operations in a money type.
The need of standardization
Money and countries are a sensitive topic and in order to agree what is what, that International Organization for Standardization ISO helps by providing a list of current, accepted currencies and their alphabetic and numeric codes.
This list is active, with new currencies entering the list and old, deprecated currencies coming out and names changing.
Despite the efforts of Microsoft, there is a gap between what is currently accepted by the ISO and what is implemented in the .NET Framework, and framework releases and patches sometimes lag behind the current standard.
It is easier for a focused, smaller library to stay current than it is for a larger framework.
NMoneys to the rescue
For the aforementioned reasons is that NMoneys exists: to provide a money value-object Open Source implementation that follows the ISO 4217 standard.
The project is a veteran with a lot of dogfooding on its shoulders and I hope that it will get more exposure and help even more people that has helped so far.
Visit the project site, read the documentation, get its binaries via NuGet and contribute if you feel like it.
You can follow my personal blog for updates and new releases.
Enjoy responsibly ;-)
Top comments (0)