Matthew Lang

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.

Comments on Controller Methods

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.

# Loads the default configuration</h1>
# (roles, trackers, statuses, workflow, enumerations)
def default_configuration
  # ...
end

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.

Comments on Model Methods

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.

To Comment or Not?

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.

I'm a big fan of both Mike Vardy and Patrick Rhone, so I was really pleased to see Mike had asked Patrick to be a guest on his Productivityist Podcast. Listen and enjoy as they chat about ideas, task systems and other great stuff.

More death defying bike riding by Danny MacAskill. This time it's back to the Isle of Skye to ride the Cuillin Ridgeline.

There were a number of bikes that caught my eye this week, but this GRÜN bike won this week's place in the Fixie Friday archives with its distinctive colour scheme.

via FGGT

Apple's choice to remove the ability to upgrade the internals of their products has me asking decisions about my own preferred hardware setup for work purposes.

Our house is light when it comes to computing power. We have a handful of devices between the family and there's a games console there for when I feel the need to be humiliated at Madden by my oldest son. As for actual computers though, with the keyboards, mice and monitors, we have a single laptop in the house. Mine.

My MacBook Pro has been my workstation for over a year now. Solidly built and still just as fast as the day that I bought it. It's also the laptop the family use to sync their photos and music to external disks for long term storage. I've been careful about seperating content between work and family. I've got a couple of external hard disks for storing pictures and music as well as a third external hard disk for Time Machine backups. Anything work related stays on the laptop, while videos, movies, pictures and music are all located on external disks.

The setup we have is fine for our needs for the moment, but ideally I would like to have seperate computers for work and family. Keeping the two seperate would mean that if one was to go, then it wouldn't be a major impact on me working. If my MBP was to pack in tomorrow then the home computer could serve for work purposes until I was back up and running with the hardware that I needed for work again.

After hearing the news of the updated Mac Minis in Apple's product line up, I was excited. These little boxes of technological joy have been on my radar for a while. While the lovely iMac has been on the wishlist for a while, the cost of it is out of our budget for what would be a computer that would be used intermittently. The Mac Mini was the next sensible choice then. With a monitor already on my desk, it makes much more sense to just buy a computer than can plug into it and allow me to use my own keyboard and mouse.

However, joy quickly turned to dismay when I found out that as a consumer, I won't be able to open up the Mac Mini and upgrade the parts that I need in the future. Like it's MacBook and iMac cousins, the Mac Mini has it's memory soldered onto the motherboard which makes upgrading in the future impossible. If you want something more powerful, you need to buy another Mac Mini with the specs you need. Hardly ideal given that in order to make these Mac Minis viable as long term computing products, the upgrades on the Apple website are higher than the market prices for similar upgrades you could do to a more open computer.

It's sad to see that Apple's products are going against this with memory now being soldered on to each of their product's motherboards. It's got me thinking again about how much do I want to invest in computing hardware in the home as I am clearly becoming more and more dependent on Apple's products. As a technology platform for ordinary consumers, Apple's products are hard to beat. They work well and the software that they provide for OSX and iOS is easy to use. I don't think for everyday use I would switch to another platform such as Google or Microsoft. It just works, it always has.

The geek in me though has me looking at Linux barebones boxes and alternatives to traditional desktops such as these miniature Linux desktops as a replacement for my laptop. I definitely want something longer lasting but also upgradeable. I'm just not sure at the moment what that setup will be. Ideally a desktop running some Linux distribution as well as a small form laptop such as a Chromebook, without the Chrome OS, could serve me for my mobile needs which at the moment are rare. That could change though.

A few decisions to make here, but I think the first is whether I could use Linux as my work environment on a daily basis. I should probably decide on that first before making any decisions regarding my desktop hardware.