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 > Describe concepts in comments

Describe concepts in comments

Bozhidar Bozhanov user avatar by
Bozhidar Bozhanov
·
Sep. 12, 11 · Java Zone · Interview
Like (0)
Save
Tweet
3.99K Views

Join the DZone community and get the full member experience.

Join For Free

It’s common knowledge that commenting your code is a must. But that’s where the wrong interpretations come. “// incrementing i” above “i++” is one extreme example of useless comments, but what can be often observed is “shallow commenting” – i.e. comments describing what exactly is done, but not why. In other words programmers may forget to document the concepts and ideas behind the code.

For example, imagine you see ClientDocumentIndexer and DocumentIndexer. What’s the difference? The code may have comments explaning what happens when sending the documents to the search engine, but there is nothing about the difference between the two. Same goes for things like DownloadRecord and DownloadLog. And for millions of examples throughout thousands of codebases. The comments in these classes fail to communicate their business purpose. Then there is the FooListenerBuilderFactory – yes, I know all these patterns, but it still doesn’t make sense without an explanation why each of them is required.

Sometimes there is sufficient explanation about these concepts in some intranet document. There’s just no link between the code and the description. Adding a link will most likely be sufficient for the reader to understand what’s the purpose of a given class or method.

What if there is no spec/document? Then you’d have to write that “document” in the code. Don’t be verbose – just outline the reason for the class existence, and how it fits into the program flow. Each piece of code should make sense to someone that is not familiar with all the business requirements.

Sounding obvious? Well, if it was, you wouldn’t be seeing code that is hard to understand out of context.

To summarize:

  • document the concepts and ideas of a class, not (just) how it functions internally
  • if relevant, explain the reason for a class existence and how it differs from similar classes
  • document the context of a class – how it fits into the program flow
  • link requirements documents, if such exist

 

From http://techblog.bozho.net/?p=463

code style Concept (generic programming)

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • How Java Apps Litter Beyond the Heap
  • Creating an Event-Driven Architecture in a Microservices Setting
  • SSH Tutorial: Nice and Easy [Video]
  • Five Tips to Fasten Your Skewed Joins in Apache Spark

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