Continuing my series on reading Redmine, we'll take a look at commenting.
Next to tool choice, comments is another topic that can cause heated debates amongst developers. As a rule, I rarely comment my own code. I just don't see the need to comment it. I try to be as expressive as possible in the code I write and although it usually is more verbose than other developers who I have worked beside, I know that by expressing my code, it becomes easier to read and understand.
Having worked on a number of different code bases for clients I've started to look at commenting in a different light. In the past I would rarely comment but now that I am working on code bases for different clients, it can be advantageous to comment your code. When I started reading the Redmine code I noticed a similar use of comments in the Redmine code to what I had in mind for commenting on my client's code. Here's what I found out.
Open Source License Everywhere
Having not worked on any major open source applications (yes I should rectify this), I was surprised to see the open source license located on each file within the Redmine source. Yes, within each file. Every model, controller, helper and almost all Ruby source files that I could see included a copy of the GNU General Public License (version 2).
My only critique against this is that if the license was to change then it could be something of a task to update the license on each file within the application, however in order to ensure that the license for Redmine is fully understood, then it does make sense to include the license in each source file.
The reason I have included this is that I do view the license as a sort of comment. It's not code but it's also not expressing the intent of the code in the typical way that a comment does. It does describe how the source code can be used so could be viewed as a comment.
One thing that stood out from the source code was the use of comments on controller methods. This makes senses in the cases I seen, as some controller methods didn't follow the traditional RESTful verbs and some required an explanation of the intent of the method. It was good to see that a single or double line comment was frequently used to explain the controller's intent.
{% highlight ruby %}
# Loads the default configuration
# (roles, trackers, statuses, workflow, enumerations)
def default_configuration
# ...
end
{% endhighlight %}
This is good from a documentation point of view as it means that other developers working on the same method will immediately see what this method does. Most controller methods were fairly straight forward to read but there were a number that required just a single line to explain the method further.
Putting aside the argument of where the business logic in a Rails application should reside, let's just assume that in Redmine's case it is in the correct place, mostly within the ActiveRecord models. I say most as there is also a fair degree of code spread out into controller, helpers and in the lib folder too.
So if most of the business logic for Redmine resides within the ActiveRecord classes then where's the documentation for each method? It was something I found unusual given that the controllers were documented well. From scanning the models it was clear that only about half the model methods were commented. It should be mentioned that there were a number of methods that didn't require comments, but then there were a few places where a comment might have been advantageous.
The Redmine source itself is a typical Rails applications without any architectural surprises. It shouldn't surprise most developers familiar with Rails that it is indeed straight-forward to follow. Given my history with commenting in Rails applications, I was surprised to see such a wide use of commenting within Redmine but without using RDoc.
It has given me food for thought on commenting on the Rails applications that I working on at the moment including my own. I've always just viewed my code as code the I alone will read but that may not be the case. If someone else was to read it, what would they think? That's an exercise for another day, but this look at commenting with Redmine has shown some good examples of where commenting can be an advantage.
