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.
