DZone
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
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Enterprise AI Trend Report: Gain insights on ethical AI, MLOps, generative AI, large language models, and much more.

2024 Cloud survey: Share your insights on microservices, containers, K8s, CI/CD, and DevOps (+ enter a $750 raffle!) for our Trend Reports.

PostgreSQL: Learn about the open-source RDBMS' advanced capabilities, core components, common commands and functions, and general DBA tasks.

AI Automation Essentials. Check out the latest Refcard on all things AI automation, including model training, data security, and more.

Related

  • High-Performance Java Serialization to Different Formats
  • Java 11 to 21: A Visual Guide for Seamless Migration
  • Creating a Deep vs. Shallow Copy of an Object in Java
  • Generics in Java and Their Implementation

Trending

  • Building Safe AI: A Comprehensive Guide to Bias Mitigation, Inclusive Datasets, and Ethical Considerations
  • AI-Driven API and Microservice Architecture Design for Cloud
  • The Future of Agile Roles: The Future of Agility
  • Integrating Salesforce APEX REST
  1. DZone
  2. Coding
  3. Languages
  4. Why Should I Comment My Code?

Why Should I Comment My Code?

Learn how to write source code comments that help to understand the code much faster.

By 
Ralph Soika user avatar
Ralph Soika
·
Dec. 27, 22 · Tutorial
Like (6)
Save
Tweet
Share
5.2K Views

Join the DZone community and get the full member experience.

Join For Free

Today I want to write about why comments are so important in software development and how you can improve them. For me, the most disappointing thing about good source code is when it is insufficiently commented on. And this happens with closed code in the same way as with Open Source code. In the worst case, and this is usually the most common, the source code is not commented on at all. Especially in open-source projects, this is a disdain against the community reading your code. But even in internal software projects, I consider missing comments to be bad behavior towards your colleagues, which should be avoided.

Of course, we all know the funny answers in this context. “Good code doesn’t need any comments” or “Take a look into the source code if you don’t understand something.” Is it laziness or ignorance not to write comments? No, I believe that many developers simply do not know how to write good comments. For this reason, I would like to explain here a very simple rule on how to really improve your source code through comments.

Don’t Explain to Me the What and How!

The biggest mistake you can make when writing comments is assuming you have to explain what you are doing. In this case, you write comments that explain the obvious.

Java
 
/**
 * Builder Class to build Events
 */
public class EventBuilder { 
 ....
}


As long as the name of a class or method is not absolutely meaningless, a name should explain the usage of a class or method. So please do not explain that a Builder Class builds an object or a getter method returns an object. Writing such a comment is a waste of time. By the way, the same applies to those who have to read this kind of useless comment.

The second example of bad comments is explaining how the code works.

Java
 
/**
 * Build the event and return it.
 */
public T build() {
   ....
   return event;
}


Of course, you shouldn’t assume that the users reading your code are complete idiots. You can assume that other developers can code just as well as you do. And explaining software patterns in the comment of a method or class is pointless.

So now we have seen what bad comments are. But what does a good comment look like?

Start With Why

There is a great book from Simon Sinek with the Title “Start with Why: How Great Leaders Inspire Everyone to Take Action“. The core message of this book is, that you always should start by explaining the ‘Why’. The ‘What’ and ‘How’ are usually explaining things later in more detail. For software development, the  ‘What’ and ‘How’ is indeed in the code and need no comments in many cases. 

So starting with the "why" can make source code comments much more useful – for yourself and for others. Starting with "why" makes you think about what you’re actually doing. So going back to my previous examples a comment may look like this:

Java
 
/**
 * When using Events in the client, the EventBuilder may help 
 * to construct them in the correct way more easily. 
 */
public class EventBuilder { 
 ....
}


Instead of describing what the class is, answer the question of why you have invented it.  The same is true for methods. As explained before if I want to understand the "how," then I can read the source code in detail. But why does the class or method exist? This is what a comment is for:

Java
 
/**
 * To display the summary of an invoice in the client, 
 * this method calculates the summary including all taxes.
 */
public float summarizeInvoice() {
   ....
   return event;
}


I don’t want to go into more detail. It’s obvious that the better you explain why you have written a class or method, the more it helps others like yourself to understand your code. So when you start writing your next code, think about why you’re doing this and comment that into your class or method header. You’ll see – your colleagues and your community will love it and will much prefer using your code.

IT Open source Software development Object (computer science) Data Types Debug code code style Java (programming language)

Published at DZone with permission of Ralph Soika. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • High-Performance Java Serialization to Different Formats
  • Java 11 to 21: A Visual Guide for Seamless Migration
  • Creating a Deep vs. Shallow Copy of an Object in Java
  • Generics in Java and Their Implementation

Partner Resources


Comments

ABOUT US

  • About DZone
  • Send feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

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

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: