Should developers write documentation?
Yes. Yes, they should.
Oh. You want to know why developers should write documentation? Fine.
Why Developers Should Write Documentation
Developers should write documentation because it makes it easier for both you and your coworkers to use your code. Well-written code is easy to read and understand. Documented code, on the other hand, is a gift to everyone—even to the coder that created it.
Writing documentation makes you a more valuable developer and will help your career. Documenting your code makes you a better developer and helps you design better systems.
Documentation Helps You Maintain Your Own Code
Yes, that’s right. Documentation will help you maintain your own code. Why? Because at some point in your career, probably at many points, you’re going to have to open up something you wrote weeks, months, or even years ago, and you won’t remember a blessed thing about it. If you’re new to programming, you might find that hard to believe. If you’ve been around a few years, you know exactly what I’m talking about. Life comes at you fast, and two months ago feels more like two years ago after you’ve worked on several different projects.
Documentation Helps Your Coworkers
Another common situation is that, while you’re busy working on one thing, something else you wrote breaks or needs new features added. Your boss decides that it’s better for someone else to do the work so you can continue with what you’re already working on. (Trust me when I say that you’ll appreciate this. New stuff is always more fun than old stuff.)
What happens when the other coder opens up your code? Will they be able to figure it out? Or will they need to pull you away from what you’re working on to get them set up anyway? Wouldn’t having some documentation on hand make it easier for you stay focused and for your coworker be productive?
This is especially true in today’s world, where one of the most common demarcation points between modules are application programming interfaces (APIs). How the API works might seem obvious to you. It might not be so obvious to a newcomer.
Comments Are Not Documentation
This is probably a good place to bring up another important point: Comments are not documentation.
I want to make sure you heard me.
Code comments are not documentation.
Comments are for calling attention to specific pieces of code. For example, you might want to explain why you decided to hard-code a specific value instead of making it configurable. That’s a comment. Or you might want to call attention to some code you had to work out to overcome an idiosyncrasy in a third-party API or service. That’s another comment.
Comments should be small and specific. A comment in one module that refers to another will be missed or misunderstood.
There are tools that turn comments into documentation. They usually produce hyperlinked API docs by looking at the code and specially annotated comments. Those tools are great, but they’re not a substitute for a document with a beginning, middle, and end.
Documentation Is About the Big Picture
Documentation is focused on the big picture. How do the different modules in your code work together? How is it configured? How do the different configuration values work together or against each other? Does the code have any special runtime or build time dependencies?
Taking the time to document your code at this “higher” level often helps you understand it better. By stepping away from the code and forcing yourself to think about what it does, how it does it, and how each of the pieces fit together, you gain a better picture of what you’ve created. You may even find yourself going back and making some tweaks to your design based on what you discover as you write your docs.
Some developers advocate for writing the documentation before you start writing code. I usually don’t go this far, but there have been occasions where I benefited from time spent writing out how something will work in English before I started working in C/C++ or Java.
Documentation Makes You More Valuable
Regardless of when you produce it, documentation that your coworkers or clients can use makes your work more valuable. And if your code is more valuable, then so are you.
Writing ability is one of those inaccurately named “soft” skills that won’t necessarily help you get hired but will help you advance once you join a team. If you can write, you can communicate effectively with your coworkers; including your boss. This often leads to more challenging jobs and more visible roles. That usually means more pay, or at least a résumé that will help you land that next job.
(Bad) Reasons to Not Write Documentation
Documentation Always Sucks
“There’s no point in writing docs. They’re out of date as soon as they’re done and always suck.”
This is one of the most common and most infuriating reasons to not write documentation. It’s nothing but laziness.
“Why plow the roads? It’s just doing to snow again.”
“Why eat? You’re just going to get hungry again.”
If your code breaks, you fix it. If your documentation breaks, then you should fix it, too.
Developers Should Focus on Developing
“Developers shouldn’t be writing docs, they should be coding.”
In order to agree with this, you have to agree that producing documentation and producing code are mutually exclusive activities. They’re not.
I covered this above, but it bears repeating here: Writing documentation can make your code better. Development is an iterative process, and making documentation part of the process makes code better.
Your Code Is Your Documentation
No. Your code is not your documentation.
Code is code. Code is for coworkers. Good code is easy to follow. So easy that it’s usually a little bit boring. When you open a source file that contains good code, you can read the code and figure out what it does.
But code isn’t documentation. It doesn’t give you the big picture. Why does Object1 need to talk to Object2? You can try to cram this into comments, but where? In Object1 or Object2? Code has the “how” and hopefully makes the “how” obvious and easy to follow. But it often lacks the “why.”
And, of course, there’s the obvious question. What if your clients don’t have your code? If they’re talking to a RESTful service or linking to a closed-source library, they can’t see your comments.
Yes, Developers Should Write Documentation
A developer’s most important skill is the ability to write fast, reliable, and reusable code that their teammates can understand. But the ability to communicate with those teammates is a close second, and part of the communication is in the form of documentation.
Get in the habit of writing documents as you design and implement your code, even if it’s for your eyes only. Just like developing coding skills, writing skills come from practice. Your career will benefit.
This post was written by Eric Goebelbecker. Eric has worked in the financial markets in New York City for 25 years, developing infrastructure for market data and financial information exchange (FIX) protocol networks. He loves to talk about what makes teams effective (or not so effective!)