Code Tells Story - Eric Zhou

Good code is simple, follows conventions, and has clear names. Writing readable code makes debugging easier and saves time. Whether working solo or with a team, code can become obscure over time, making it essential to write clear code.

Imagine explaining code to someone who doesn't know its purpose. Describe how it fits into the larger project, why decisions were made, and highlight any tricky parts. This is called "telling the story of the code." Write code that tells its own story, making it easy for others to understand.

Code should be straightforward and easy to follow. Aim for code that doesn't require explanation, but if it's complex, at least make it well-documented.

#Tell The True Stories

Code tells its own story by conveying its intent and purpose in a clear and concise manner. Good code is easy to understand and follow, just like a simple story.

Some comments may be incorrect or outdated, which can lead to bugs and confusion. While comments can be helpful for code readability, not all comments are good.

For example, if a comment claims that a function always returns a valid result, but the function actually returns an error in some cases, it can lead to a bug that's hard to find. This is because the comment is out of date and doesn't match the actual code.

The solution is to use asserts instead of comments. An assert is like a comment that's checked by the code at runtime. For example, instead of writing a comment that says "this function always returns a valid result", you can use an assert statement that checks if the result is valid.

By using asserts, you can ensure that the code is always telling the truth and won't lead to bugs. This makes it easier to understand and debug your code, and helps to avoid the pitfalls of outdated comments.

#Ensure the Story Has a Purpose

Sometimes comments aren't wrong, just useless. A common problem is when a fixed commenting style is enforced across a project, leading to comments that don't add any value.

For example, consider this code that follows a project-wide rule to document all functions with Doxygen: This comment is technically correct, but it doesn't provide any useful information. It simply restates the function name.

When comments accompany function declarations, they can take up a lot of space and make it hard to find the actual code. This is especially true if the comments are awkwardly formatted.

The only potential benefit is that Doxygen documentation can be generated from these comments. However, this advantage is often outweighed by the effort required to create thoughtful comments.

In reality, programmers usually rush through commenting, aiming to meet mechanical standards rather than providing valuable information. As a result, the documentation becomes a list of uninformative entries that don't offer any insights into the code.

#Telling Good Stories

A good comment helps the reader understand the code by explaining something that isn't obvious. It shouldn't just repeat what's already written in the code.

Good comments also serve as a guide to help the reader navigate the code. They break up the code into separate sections, much like spaces and punctuation do in writing. This makes the code easier to read and understand.

Adding descriptive names, spacing, and comments to the code makes it much easier to follow. Good comments provide context and explanation, giving the reader a sense of purpose and meaning.

Think of good code as a song with lyrics. The code is like the music, and the comments are like the lyrics. Both are important and work together to create a clear understanding of what's happening.

Code editors often color-code comments, making it easy to focus on the code or comments separately while still keeping them together. This is similar to reading sheet music with lyrics.

Remember, good comments complement the code by providing context and explanation. They should pull the reader into a story, making it easy to understand the code. If you can read through the comments without looking at the code and still understand what's happening, then you've done a great job.