(First published on What the # do I know?)
In the dot net world, there are basically two types of comments:
There are your everyday regular code comments, and then there are XML documentation comments.
The purpose of comments in your code is to help clarify things to whomever is going to be maintaining the code in the future.
They are only visible inside the source code and IMHO, should mostly be used when they can save the maintainer time and effort understanding parts of your code. Writing good comments is not much easier than writing good code – and one of the modern definitions of good code is that it’s self-explanatory – and therefor in the most part don’t need comments.
XML Documentation comments, on the other hand, are a different beast altogether.
They are visible outside your source code, not only to the code maintainer, but also to the developers that are using your code. They serve an entirely different purpose then code comments.
While code comments are there to help maintainers, the XML documentation comments are there to help your users (and by that, I mean users of your code, of course).
An XML Documentation comment is for documentation, and a public documentation is a contract.
Once your code documentation goes public, you are bound by it – changes in your code must not effect the already documented behavior – at least, not without proper warnings.
For instance, if you have a public method that you want to rewrite, making a breaking change (a change that forces the code that interacts with yours also to change as well), the proper thing to do is to let your users know by first publish an intermediate version of your code and documentation, where that method stays exactly the same, but is marked as obsolete, along side the new implementation in a different, new method.
This new, intermediate version is potentially a breaking change itself, but it’s still a minor version change, so given the rules of semantic versioning it’s version should be x.y+1.0, where x is your current major version and y is your current minor version.
The more popular a product is, the more bounded it is to it’s public documentation is. Anything that’s undocumented is liable to change at your whim, but documented interfaces are a different matter. In big, high-profile products, features might stay deprecated for years, spanning over multiple versions – one example is the Text, NText and Image data types that was declared deprecated in SQL Server 2008 version, with the introduction of their successors: varchar(max), nvarchar(max) and varbinary(max). Today, with the 2017 version, they still exists, and are still documented as deprecated.
This is a direct result of the fact that public documentation is binding.
Top comments (0)