My thoughts on code documentation

Development
1

A recurring topic in every project I’ve been involved with is when and where you should use XML comments and/or annotate classes and members with proper documentation. Having played around with the Squidex code base the last three weeks, I see the same challenge.

I’ve always been very specific about this, but in real live I meet a lot of developers who don’t seem to care about this, or worse, they reject the entire concept. Some of these people claim that the only real documentation is the code itself. And although I fully agree that a well-factored and properly named class is a crucial element in achieving a maintainable code base, proper documentation is just as important.

In my opinion, these three kinds of documentation are required for every professional code base, including that of Squidex

  • Class-level and member-level documentation helps you understand what behavior to expect without having to jump into the actual implementation details. It should also explain the responsibilities and the roles the class plays in the overall design, or the member within the class. This kind of documentation is not a replacement for proper naming. Both are crucial, and one should reinforce the other. So always document the expected behavior of all your public and protected members. But, don’t add documentation that repeats the name of the member. I’d rather have no documentation at all than that kind of useless crap.

  • Inline comments, which you should use scarcely, are there to help you understand the thought process the original developer went through, to point you in the right direction, or to emphasize a particular non-trivial design decision. I use the word scarcely purposely, because in most cases, refactoring the code can help you avoid the need to have in-line comments. For instance, wrapping a complex expression in a method which name explains the goal of the algorithm can already make your code a lot easier to understand.

  • Commit comments should not only explain the nature of the change, but more importantly, why a particular change was needed in the first place. When a lot of people are involved, it becomes pretty important to be able to see why something that happened a long time ago happened. Yeah, an internal blog can help, but ultimately, it’s the source control history that will contain the really interesting changes. I’ve seen numerous occasions where I noticed some code that seem to be superfluous, but ended up being quite critical. The commit message for that change helped me understand why. Unfortunately I’ve also seen less helpful commit messages requiring me to figure out the reason the hard way.

Don’t get me wrong, Squidex looks extremely promising and may be exactly what we’re looking for, but I’m quite concerned about the lack of code documentation. Hopefully my little wall of text can convince you to change your development mindset.

2

Hi,
I don’t agree to point 1 as a general rule, especially if the method is easy but I agree to the other points.

The “problem” right now is that there are not that many PRs. Perhaps because of the lack of documentation, but I also think it is a general problem in the .NET world. Many customers with the man-power to do so have very strict guidelines in their organizations which stops them from committing code.

3

That’s fine. I suppose we align quite well. I just prefer to add docs by default, unless it doesn’t any new information. And you prefer the opposite.

The “problem” right now is that there are not that many PRs. Perhaps because of the lack of documentation, but I also think it is a general problem in the .NET world. Many customers with the man-power to do so have very strict guidelines in their organizations which stops them from committing code.

I guess we need to coach those organizations. Using open-source and contributing back is mutual beneficial. All organizations I’ve worked with have embraced this principle eventually.

4

Yes, but eventually can take a few years in some cases :wink:

1 Like
5

I think I disagree. XML/Comments eveywhere bloats the code base. I used to be in agreement with tools like Stylecop, now I find them viral and add too much noise.

I’m not entirely against it, but I believe that any documentation should be enough with a simple Summary that may document a complicated implementation or process. Anything else around how Squidex generally works, i.e Event Sourcing and CQRS should be documented outside of the code base and explained in a better detail to give a better understanding of the patterns applied within the code.

Comments obviously do add value, and they’re allowed by the compiler for this exact reason. I just would not like to see Squidex plastered with XML docs on things like a Get or Set property that says something like “This gets the property.”. I always disliked working with code bases that enforced all the stylecop rules.

6

That’s exactly what I’m proposing. We shouldn’t be dogmatic about it and most definitely not use tools for that. The rationale for this is that if you’re lucky the code is clear enough to understand what it does. But it will never explain what it is intended to do, or its purpose in the bigger picture. A good name can help here, but is usually too short to understand the real purpose. In the case, this is true, don’t dogmatically add documentation that just repeats that name.

As an example, I was looking at the examples and the IValidator interface. I couldn’t find any information on its purpose, its role in the command pipeline, nothing. A simple block of XML comments could really help explain the purpose of this interface and help you build a better mental model of how all of this fits together.

2 Likes