Zero or Bad Documentation: Fix It with Meaningful Comments

Zero or Bad Documentation: Fix It with Meaningful Comments

Jul 01, 2025

Let’s be honest — we’ve all opened up a piece of code after a few months and thought…

“What in the world was I trying to do here?”

Been there. Done that. Regretted it.

As a developer, I’ve learned (often the hard way) that writing clean code isn’t enough. If you don’t document it properly — through comments, README files, or API descriptions — you’re setting up traps for yourself and others.

So in this post, I want to walk you through why documentation matters, what to write, how to keep it simple, and the tools I use to make it painless.

Why Documentation is Often Ignored

Most of us don’t skip documentation out of laziness. We skip it because:

  • We’re rushing to meet deadlines
  • We think “we’ll remember this later” (spoiler: we don’t)
  • We underestimate how complex things get over time
  • We assume others will “figure it out” by reading the code

But remember: Code is read 10x more than it’s written.

If you don’t make it understandable, it’s like hiding a bug in a haystack and handing someone a blindfold.


Download Your FREE Cheat Sheet 👉 https://cutt.ly/OrTlJ1gc

What Happens When You Don’t Document Code

Here’s what you’re signing up for:

  • Long debugging sessions
  • Onboarding pain for new devs
  • Features that never get reused
  • Test failures no one understands
  • Future you cursing past you

Think of documentation as leaving a trail of breadcrumbs — so others (and you!) don’t get lost.

Why Your Future Self Deserves Better

Let’s put it this way: Would you want to maintain the code you just wrote?
Good documentation is like writing a love letter to your future self. It's respectful. It’s helpful. It saves time.

Whether it's a simple // why this workaround exists or a full-blown README, it's an investment in developer experience.

Let’s Talk About “Good” Documentation

Not all comments are helpful. Let’s start by cleaning up what documentation should not be:


Useless, right?


Now try this:

That’s better. Let’s look at how you can level up.

Comment the “Why,” Not Just the “What”

Explain the reasoning, assumptions, or workaround behind code — not the code itself.
📌 Good:

to known flakiness in external service
🧱 Bad:

API again

The “what” is in the code. The “why” is in your brain. Write the “why” down.


Documenting APIs and Methods with Javadoc

If you’re writing Java or Spring Boot, Javadoc is your best friend.
Instead of dumping logic in your head, describe:

  • What the method does
  • Parameters and their purpose
  • Edge cases and return values

Example:


<iframe class="custom-embed-iframe" id="blot-custom-id---3XBf2StF9" srcdoc="/**

  • Processes user login based on token.
  • @param token JWT from request header
  • @return true if login is successful, false otherwise
    */" allowfullscreen="true" frameborder="0" width="100%" style="height: 69px;">


    README.md — Your Project’s First Impression

    You don’t need a 20-page manual. Just tell people:

    • What it does
    • How to run it
    • Required environment variables
    • Setup steps
    • Known issues or limitations

    Think of your README like a friendly tour guide for your project.

    Add Context in Tests and Edge Cases

    Automated tests are great. But unexplained tests? Dangerous.

    Explain why you're testing something, not just what you expect.

    Example:

    @Test
// Verifies user is redirected after session timeout

    That simple context can prevent misinterpretation.

    Tools That Make Documentation Easier

    Swagger/OpenAPI for API Docs

    If you’re building REST APIs, you should automate your docs.

    Tools like Swagger can generate interactive API docs with minimal config using annotations.

    Boom. Instant visibility.

    MkDocs and Docusaurus for Project Docs

    Want to build a lightweight docs site? These tools help:

    • Docs – Markdown-powered, Python-based
    • Docusaurus – Built for React, but works great with Java backends too

    They look great and make collaboration easier.

    Prettier + Linting Tools to Encourage Clean Docs

    A formatter like Prettier or ESLint (for JavaScript), or Checkstyle/PMD (for Java), can be configured to enforce comment usage.

    It’s a small nudge with big results.

    Quick and Practical Steps You Can Take Today

    1. ✅ Add at least one useful comment per method
    2. ✅ Write or update your README
    3. ✅ Use Javadoc for public classes and services
    4. ✅ Add inline comments only where context isn’t obvious
    5. ✅ Start a /docs folder with setup or onboarding info


    1. Download Your FREE Cheat Sheet 👉 https://cutt.ly/OrTlJ1gc

    Conclusion: Write Code Like a Story

    Here’s my advice: Don’t write code like you’re the only person who will see it.

    Write it like you’re handing it off to someone who knows nothing about your thought process.

    Better yet — write it like that person is you, 6 months from now, with no memory of what you did.

    Documentation isn’t a luxury — it’s survival gear for teams and solo developers alike.

    FAQs

    Q1: How much documentation is enough?

    A: Enough so that a new developer (or future you) can understand the purpose of your code without asking a dozen questions.

    Q2: What’s the best tool for documenting Java code?

    A: For Java, use Javadoc for methods/classes and Swagger/OpenAPI for APIs.

    Q3: Should I comment every line of code?

    A: No. Only where intent or logic is unclear. Focus on why, not what.

    Q4: How do I write better README files?

    A: Start simple: purpose, install steps, how to run, and usage examples.

    Q5: Is documentation really worth the time?

    A: Absolutely. It saves hours of future debugging, improves onboarding, and makes your code more maintainable.


    Download Your FREE Cheat Sheet 👉 https://cutt.ly/OrTlJ1gc