2008 / April 12^th/ Reducing comments and increasing documentation

When I first started programming, my only goal was to get things to work. Now that I’ve gone past how to get things to work, I’ve reached a new point in development: maintaining my own code. I never thought that things like documentation were important when you’re dealing with your own code. I mean, you know what you’re thinking, right?

Well I was oh so wrong. Documenting your own code is critical to future maintenance. It’s been almost a year since I launched the rewrite of Poetry with meaning and it’s become incredibly frustrating maintaining the site. I realized the reason for this is lack of documentation and code testing (more on this later). Coming back to 2,000 lines of code without looking at it for 4 or 5 months is just painful. The problem with the code base is that I was taking too much time commenting the code — and no time documenting it.

Let’s take an example of some commented but not documented code:

# clean the filename
stripped_location = @file_location.gsub(/(.+)\.(.+)/, '\1')
stripped_location = @options[:redo] ? stripped_location.gsub(/(.+)_original/, '\1') : stripped_location

This code doesn’t really tell me anything. Cleans the filename? Coming back to this code months after it was written doesn’t tell me a thing.

What I should have been doing is documenting the code. Documentation to me answers the “what does this do?” question. Here’s an example of some code in progress:

module Overseer
  module Backup
    # Creates a backup for one mysql database. The resulting export will be 
    # gzipped and named with the date first and then the databse name
    #
    # Usage:
    #   Overseer::Backup::Mysql.new(:username => "webdb", :password => "ultimatetest", :host => "mysql.example.com", :database => "pwm_production")
    #   For database called "pwm_production" backed up on April 7, 2008 , the final name will be: 2008.04.07.pwm_production.sql.gz
    #
    # Options:
    # * :username - database username
    # * :password - database password
    # * :host (optional) - the database host name
    # * :database - the name of the database
    class Mysql

      attr_accessor :username, :password, :host, :database

      def initialize(options = {})
        @username = options[:username]
        @password = options[:password]
        @host = options[:host].nil? ? "localhost" : options[:host]
        @database = options[:database]
      end

    end
  end
end

I haven’t even really written anything useful yet — but by writing the documentation I’ll know what I was doing a week from today instead of just blindly looking at the code. My documentation tells me how to use the code, not what the code does.

Documenting your code also forces you to really think the functionality through. It makes you think about the architecture of your code before you write it and forces you to think about how it will be used instead of how it was written. It all comes back to the idea that code is written for humans, not machines — so why not start with writing your code 100% human style? (in text!)

1. 

   Andy Beeching

   April 12^th | #

   I quite like this mantra for documentation:

   “Comments should contain the word “because”. This way, you know that you are answering a why rather than a what.”

   I think it was from this post by Steve Yegge:

   http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html

   Anyway, since I write mainly JavaScript atm, I’m using jsDoc to document projects, and try and include a high-level outline of each object at the top of the file explaining it’s purpose. Params and other dependencies are then ‘marked-up’ with the jsdoc syntax.

   Inline comments can then still be added if there’s any finicky bit of code.

2. 

   chris rhee

   April 12^th | #

   Good call. It would especially be useful if there’s a possibility of handing the code over to someone else in the future.

3. 

   Luke

   April 14^th | #

   Always the best way! But I learnt the hard way too :( my programming style is constantly changing, so not only am I disgusted at my naivety when looking at an old project, I’m also at a loss most of the time to work out what’s going on. Gonna persevere and get this on all my next stuff :)

4. 

   Colin Devroe

   April 14^th | #

   I find my documentation/commenting style continues to change over time. When my code will be open sourced, I’m much more aware of how I write the comments, typically I just add a simple description with an “accepts” / “returns” type of information.

   I would definitely like to find a definitive style… and also find a way to “strip comments” if needed (like in JavaScript).

5. 

   Alex Curylo

   April 22^nd | #

   “without looking at it for 4 or 5 months is just painful.”

   Heh. “Months?” Friend, when the OS X transition hit, I had porting projects show up with code I hadn’t seen since I shipped off to the contractors over a DECADE ago. Indeed, one of my current projects right now is to get over to Cocoa a project that has files I haven’t looked at since they were first written in 1998, just shy of that.

   The way I put it is,

   1) Your first … mmmm … 18 months in the industry you code as cleverly as possible.
   2) Then you realize no one cares how clever your code is, including you a couple weeks at most after writing it. So you switch to coding how you figure will actually impress your coworkers/superiors/clients, namely to execute as efficiently as possible.
   3) After some time you realize that coding with execution efficiency in mind is a mug’s game since you can rarely guess where the actual time-worthy chokepoints to care about efficiency are.

   This is when you attain true enlightenment, and you realize that The Best Code is actually code which is maintainable. That means someone else can take over working on it easily to free you to do more interesting things, plus you can use it yourself easily months/years/decades later. Certainly, I have received many -many- more heartfelt kudos and good recommendations through the years along lines like “Wow!! This is absolutely the EASIEST code to port i have EVER seen!!!” then I ever have for programming I’ve done with any other aim than ‘maintainable’ in mind.

   I think there is no next step, and you just refine that epiphany. “Complete unit test coverage” is the next step on my personal path I believe. Well, after “finding a javadoc type system for automatically parsed documentation that honestly isn’t far more trouble than its benefits.”

Name

Email (will not be published)

Website (optional)