Is Self-Documenting Code Reality?

When documentation and comments fail, maybe we just need clearer code

Last week I learned that one of the benefits of choosing GraphQL over REST API’s is that GraphQL is inherently self-documenting. This was during a discussion on Twitter Spaces that I co-hosted with Ali Spittel to discuss the benefits and differences of using the two most common approaches to API development at the moment.

Being self-documenting is not enough of a benefit in itself. There are many other valid reasons when making such an important architectural decision such as latency or application complexity. The introspective nature of GraphQL however does make the idea of reducing documentation overhead an attractive follow on benefit, given the struggles of developers documenting code.

As organizations grow and as more API’s are developed, the need for clear and useful documentation is increasing. However the likelihood of documentation staying up to date (if documentation is even available) is a crap shoot. Having to cobble together various REST end points to figure out how to formulate a request can become a time consuming, non-trivial effort.

The theory of self-documenting code sounds great. If write your code in such a way that it can be understood by others as they are reading it, you reduce engineering overhead, ship features faster, and produce higher quality code. Running code is only one consideration:

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. - Martin Fowler

Ultimately it is humans that are tasked with fixing, integrating, updating, and modernizing the code. If those same humans struggle to understand the code and the thinking behind the code, then it leads to inefficiencies unraveling code and downstream issues of introducing bugs or breaking unknown dependencies.

The struggles of convincing developers to write documentation is well documented, pun intended. Of all the things that takes up a developer’s day, documentation is last on that list of priorities. No one is measured on how many lines of documentation written or user reviews of documentation, developers are evaluated on writing working code and shipping features.

As a stop gap for actual documentation, developers leave comments. Comments create their own problematic experiences and can cause just as much confusion or lead developers to go down the wrong rabbit hole. Because comments are not code, it is easy to forget that when the code changes, the corresponding comment should also change.

This is why self-documenting code is continuously promoted. It obviates the need to have a separate stream for documentation and is the one thing other than going down the route of external software driven solutions that can have a positive impact in software productivity.

Going back to our discussion on the self-documenting nature of GraphQ, is it really that much better from a documentation standpoint? Not quite, as one of the key developers of GraphQL explains:

“An important question to ask when designing APIs is ‘Would a new engineer understand this?’ Naming things that adhere closely to what those things actually do is really important to make this experience actually work.” - Lee Byron

It helps if your developers are not naming important objects, functions, and variables exciting names like HappyFunBall or using random letters of the alphabet for example. While this should be a given, enough code reviews over time will convince you that it is a lesson rarely heeded by developers and engineering teams.

This is where the shiny and beautiful world of theory slams in to the cold hard reality of the real world. This tweet should be framed in a museum as a universal truth of documentation:

Self-documenting code is a myth perpetuated by those who hate to write documentation. - Nicholas C. Zakas

People will be people. Even if we way we will follow the processes and standards, it is easy to fall into common habits, take shortcuts, and rush things to get work off our queue. If it is not a habit, we view added work as an obstacle to avoid.

Habits can be formed though through deliberate practice, reinforcement, and usage. One of the markers of high performing engineering teams is that standards are engrained as good coding practices and reinforced through onboarding, peer & mentor interactions, code reviews, and a culture of high standards.

When looking at how those teams are able to write code that gets closer to the ideal of self-documenting, there some common practices that are observed. I distilled those down to five practical and easily implementable ideas:

  • Avoid hard-coding constants – If you have a loop that runs five times, why five times? Instead use a named constant that is described the why behind the constant and then use the name in code.

  • Use clear names – As explained before in talking about GraphQL, using more descriptive names helps. Do not go overboard though and use names that are so long that they become a chore to read and use.

  • Refactor named functions – Often just separating out complex or confusing code within its own separate function with explicitly described names can do wonders for readability and clarity.

  • Write smaller methods – A big monolith of code that does a lot is hard to follow. Write code in a more modular way from the onset helps break things up.

  • Format the code – Cramming all the code in a big block is a pain to decipher. Readability is greatly enhanced when the code is spaced out and indentation clearly shows distinct code blocks.

Much of what is described above is both common sense and easy to begin using. Despite the joke about common sense not being all that common, developers generally appreciate and want guidelines and systems that make their work easier.


Are we going to get closer to a future of self-documenting code? A more likely scenario is that AI driven software solutions will emerge to augment and improve upon what engineers write in terms of code practices, code clarity, and auto-generated documentation. In the meantime, the combination of better coding practices, more thoughtful use of comments, and community oriented tools where developers can share, collaborate, and help each other will be the methods that help make sense out of the ever growing complexity of our codebases.

What practices do you use for writing better code on your teams? How have you been able to overcome the challenges of lack of documentation?

Mark Birch, Editor & Founder of DEV.BIZ.OPS

Leave a comment

It has been almost a month since my last newsletter, so what has been going on in my world? Well, partly it was vacation but also I have been busy on three projects.

The first is that my Chrome extension LinkedIn Hashtags reached 3,000 downloads! It is a tool to find hashtags with the most followers so LinkedIn users can improve the reach of their posts. I will share more periodically as I continue to build out more functionality and use AWS as a way to do this easily and cost effectively.

The second is that I have been experimenting quite a bit in using and hosting talks on Clubhouse and Twitter Spaces. I am convinced that the Social Audio market is going to be massive, and many big tech players like Slack, Reddit, Facebook, LinkedIn, and Spotify have made announcements about adding live audio to their platforms. I have been launching shows in the Americas, EMEA, and APAC for the AWS Startups club and Clubhouse, so follow the club to get alerts for future shows. If you need an invite, I have plenty to share (note still iOS only till Android is released in May).

The third is that I have always wanted to make this DEVBIZOPS newsletter into more of a community to allow all of you reading this weekly publication to meet, share, and collaborate with each other. I have decided to finally go ahead with those plans and open up the Slack group for DEVBIZOPS to all readers. To get that going however, I need some help to moderate and be involved in the discussions from time to time. The timetable for launching this is in June, but in the meantime please do let me know if you want to be involved.

The last update I wanted to share is that I am finally heading to Singapore. I am super excited to finally be back after over a year. To all my Singapore readers, if you have any good leads on places to live, I would welcome all the suggestions!

Want to learn more about DEVBIZOPS and read more hot takes about IT, technology, and working smarter. Receive our weekly newsletter by signing up to our Substack!