Finding Your Way Through the Code

One of the things that you can do to make your code—and by extension your project—accessible to your adopter community is to make the code as easy to find and navigate as possible. I have some thoughts about making code easy to find that I’ll share another day. Today, I’m thinking about navigating. By navigating, I mean finding your way around in the code.

Personally, I like self-commenting code. I tend to try and choose my identifiers carefully (checking for spelling, of course) so that the names of my types, variables, methods, functions, whatever, are as meaningful as possible. Further, I tend to try and keep my methods (functions, whatever) as short as possible, factoring my code into collections of fine-grained methods, each with as descriptive a name as possible. Unfortunately, fine-grained factoring comes with its own set of problems, not the least of which is the navigation issues that manifest with a large number of methods.

However, self-commenting code only takes you so far. I like to explicitly comment my code as well. Public APIs should, naturally, have comments describing their use, limits, etc. But why stop there? I also like to comment private code, and make prolific use of comments inside methods. One of the last things that I tend to do is build a comment for each class that describes how the class fits into the overall picture, how it is used, etc.

I’ve spent some time today looking through some of the code that I’ve written for the Usage Data Collector (UDC), the Examples project, and the Eclipse IDE for Education (IDE4EDU) project. The UDC is probably the most comment-complete of the group, but the others don’t lag too far behind. I still have more work to do, but I suspect that this will always be true.

One of the reasons that I like to comment even private things in my code is entirely selfish: for all intents and purposes, the me of six months from now is a completely different person from the me of today (how’s that for introspection?). When I revisit my code to make changes, the help that I get from Mylyn to find out where I left things will be a great boost, but I need more help. I’m simply not going to remember what I did and why. Comments help me sort that out. I hope that they help others as well.

This entry was posted in Community. Bookmark the permalink.

2 Responses to Finding Your Way Through the Code

  1. Achim Demelt says:

    I absolutely agree with you. I cherish those moments when I review a piece of code I’ve written some months ago and I find 5 lines of comments explaining why I wrote the following single line of code the way it is, and not in any other way. And I like it even more if I find such comments in someone else’s code.

  2. Dave Carver says:

    I highly recommend reading and applying what you like from “Clean Code” by Bob Martin. http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s