November 4, 2020
Self-documenting Code
Programming Principles
Title:
How to Write CODE That Documents Itself
By:
Infallible Code
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