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

How does AI transform chaos engineering from an experiment into a critical capability? Learn how to effectively operationalize the chaos.

Data quality isn't just a technical issue: It impacts an organization's compliance, operational efficiency, and customer satisfaction.

Are you a front-end or full-stack developer frustrated by front-end distractions? Learn to move forward with tooling and clear boundaries.

Developer Experience: Demand to support engineering teams has risen, and there is a shift from traditional DevOps to workflow improvements.

Related

  • Why Documentation Matters More Than You Think
  • Why and How to Participate in Open-Source Projects in 2025
  • Bonsai Checklist: 5 Rules to Make Your Open-Source Project Popular
  • Solving a Common Dev Grievance: Architecture Documentation

Trending

  • Defining Effective Microservice Boundaries - A Practical Approach To Avoiding The Most Common Mistakes
  • Altering XML Tag Position Using Mule 4 With Basic Authentication
  • Software Specs 2.0: An Elaborate Example
  • The Rise of Self‐Service Platforms: How Cloud Development Environments Are Reshaping Dev Culture

Barely Sufficient Documentation

Properly documenting code execution and explanation are not always necessary in the code itself, but it can go a long way toward successful repetition.

By 
David Bernstein user avatar
David Bernstein
DZone Core CORE ·
Feb. 09, 18 · Opinion
Likes (6)
Comment
Save
Tweet
Share
6.6K Views

Join the DZone community and get the full member experience.

Join For Free

In Agile, when we say "barely sufficient documentation," we're not referring to user documentation. User documentation has been notoriously bad throughout the entire history of the software industry. As an industry, we must do much better with user documentation than we have in the past, but this post is not about user documentation — it's about internal documentation. It's about documenting the design and the code for other developers so that it will be more understandable and easier to work with later.

There are two important aspects to internal documentation, one of which is often neglected: documentation to express what the code is doing, and documentation to express why the code is doing what it's doing.

In traditional software development, we spend an enormous amount of effort documenting what the code does. We do this with design diagrams, specifications documents, and comments in the code. But this kind of documentation can actually become an impediment to maintainability rather than an aide to it.

The ultimate document that explains exactly what the code is doing is the code itself. Anything else is a distant second and as we write more documents that express what the code does, or pepper our code with comments that express what the code is doing, there is a tendency to make the code itself less expressive. This is a mistake.

The reason we use programming languages rather than hexadecimal machine instructions to make a computer do something is so that the instructions are understandable to us, the people who write and maintain the code. We have a very different set of concerns than the computer does. The computer isn't trying to understand the code we write, it simply executes it. But in order for us to change that code, we must understand it. And so we write our software in an intermediate form that's comprehensible to us and can get compiled down into something the machine can execute.

If you look at the code that's generated from our compilers it's highly efficient. And if highly skilled programmers were willing to sit down for many hours they might be able to write code that's even more efficient. But efficiency is not our only concern. We're also concerned with understandability. And if we have to trade some efficiency for greater understandability then it's often worthwhile to do that.

As we take these ideas to their logical conclusions, we realize that the bulk of programming is all about communication. Our jobs as programmers is to make our code expressive so that it's understandable, not just to us but to others as well. And we make code understandable by using metaphors and analogies as well as good intention revealing names to model the domain we're working in. We should name methods for what they do so the name of the method becomes the most important form of documentation.

In the past, I have been accused by managers of encouraging developers to write uncommented code and while this is true I have a good reason for it. Software developers don't like redundancy and if they know they have to write a comment that says what the code was doing, they'll tend to rely on that comment to communicate the intention of the code rather than the code itself. When this happens the code becomes less expressive and it can be a drudge to read.

Instead of writing a lot of comments in code, we should find ways of communicating that information with the code itself so our code is more expressive and there's less need to comment on what the code is doing. However, using block comments to express why the code is doing what it's doing can often be very helpful and appreciated by the people who maintain the code.

Documentation code style

Published at DZone with permission of David Bernstein, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Why Documentation Matters More Than You Think
  • Why and How to Participate in Open-Source Projects in 2025
  • Bonsai Checklist: 5 Rules to Make Your Open-Source Project Popular
  • Solving a Common Dev Grievance: Architecture Documentation

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and 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
  • [email protected]

Let's be friends: