Self-documenting Code with InfallibleCode

November 4, 2020

Self-documenting Code

Programming Principles


Title:
How to Write CODE That Documents Itself

By:
Infallible Code


Youtube – Informational

Description:
Quick rundown of how to make your code more self-documenting and reduce the need for comments.


Overview

Removing Old Commented Out “Zombie Code”

They suggest continually removing old code that has been commented out to save for later possible use. They call this type of code zombie code, and say it is generally not worth saving and if anything can cause issues. It can be confusing extra amounts of information, or someone may be more likely to reactivate it when unnecessary in a group project setting.

Some Cons of Extensive Comment Usage

They suggest keeping comment usage to a minimum and having the actual code itself better describe what it does. This starts with the basics of effectively naming variables, but also leads into all around more readable code.

One quick example they run through is a drawn out if statement check where they pull out the bools checked and make them into their own new bool variables where their name now indicates their purpose, but perform the same check. They supplement this by using expression bodies to deal with the simple bool check variables they have now created to keep them condensed and highly readable.

Summary

This is not a perfect solution since it can lead to creating a lot of small methods throughout the code that could possibly lead to less runtime efficiency when done in great numbers on huge projects. It is a very nice option to at least keep in mind even in those cases however, and can be a great asset for readability on smaller projects for sure.

via Blogger http://stevelilleyschool.blogspot.com/2020/11/self-documenting-code-with.html