Key points about knowledge management from "The Art of Readable Code"

This month, I read The Art of Readable Code: Simple and Practical Techniques for Writing Better Code on Kindle.

I wish I'd read this book years ago. As a technical writer and knowledge management specialist, the first part focuses on knowledge management and best practices for documentation within code. I found those topics interesting, especially since coding is only a hobby of mine and not a daily work activity.

What I enjoyed about the book

The beginning of "The Art of Readable Code" describes what I've found to be the laborious and unclear part of writing code in my free time: describing what's happening but only where necessary. The first half of the book guides the reader on how to best write code and leave comments for future reference or for others to reference.

Cartoon strip from "The Art of Readable Code"

Key takeaways

The kind of tacit knowledge that often comes with coding is difficult to share in an easily digestible format, whether written or verbally. However, I think the authors did a great job of explaining how to document that knowledge to help others gain from and build on that code, and address ideas and concerns.

Make our code easy to read

Making code easy to read can be subjective, and leaving comments can add time to finalizing code. But keep this in mind: We may need to refer to our own documentation in three weeks, three months, or three years. We can't guarantee knowledge retention amongst ourselves or our peers, so clearly documenting ideas or concerns is vital for saving time in the future.

The goal with comments or streamlined, self-explanatory code is to help our future selves and others to sufficiently understand code that may:

• be difficult to understand,
• affect other parts of the code, or
• be improved on in the future.

"We may need to refer to our own documentation in three weeks, three months, or three years. We can't guarantee knowledge retention amongst ourselves or our peers, so clearly documenting ideas or concerns is vital for saving time in the future."

By sharing our knowledge in code, we can quickly remember why our code works a certain way and describe to others how they can improve that code later on. And again, we can help ourselves and others save time—for example, on retrying fixes, understanding what a function is, or explaining how a function can be improved upon later.

Consider our audience

When sharing knowledge in code, we should consider our current target audience and our future self and future colleagues who may need to refer to that code.

Some examples of why we need to consider our audience include:

• Organizations hire new employees who aren't familiar with the its products or culture.
• People take on new roles.
• Organizations shrink and need others to take on additional responsibilities.
• We naturally forget knowledge over time if we don't actively use it.

In both of these cases, people will need to read and understand our code. Imagine how much time we could save for ourselves and others by leaving a well-documented thought or streamlining code to be self-explanatory without needing comments to explain what the code does.

"Sharing our knowledge empowers others to use their unique skills and experiences to further build on or improve on that code.

Another positive effect of considering our audience and sharing our knowledge in code is that people will be more likely to contribute. Think of the old adage "strength in numbers." Sharing our knowledge empowers others to use their unique skills and experiences to further build on or improve on that code.

If we can get more people contributing, whether it's inside the code or in a knowledge base, we can foster a strong culture of documentation and knowledge sharing.

Exhibit humility in code comments

Another part of the book that I found interesting was the authors' suggestion to document where parts of the code could be improved.

This honest approach and self-critiquing of one's code takes quite a bit of humility and psychological safety within an organization to be effective. With this approach, an entire organization or a small team can foster a culture of learning that engineers—both current and future—can benefit from.

Wrap-up

Since I'm not skilled at writing code, the last half of the book was a little difficult to completely understand. However, I still found value in the content and could imagine re-reading parts to gradually gain a better understanding of the best practices that the author describes.

If you write code for work or for fun, I highly recommend reading The Art of Readable Code: Simple and Practical Techniques for Writing Better Code. The content was enlightening and I could imagine revisiting certain chapters to better understand how to write better code.