DZone
Java Zone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Java Zone > Finding Your Way Through the Code

Finding Your Way Through the Code

Wayne Beaton user avatar by
Wayne Beaton
·
Jul. 22, 09 · Java Zone · Interview
Like (0)
Save
Tweet
3.64K Views

Join the DZone community and get the full member experience.

Join For Free

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.

From http://dev.eclipse.org/blogs/wayne

code style

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • What I Miss in Java, the Perspective of a Kotlin Developer
  • Automation Testing vs. Manual Testing: What's the Difference?
  • How Java Apps Litter Beyond the Heap
  • 12 Modern CSS Techniques For Older CSS Problems

Comments

Java Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

DZone.com is powered by 

AnswerHub logo