I'm trying to clean up some of my code using some best practices, and read that comments are almost always a bad idea for future maintainability. I've managed to get rid of most of them by refactoring to methods with good names.
However, there are several comments sprinkled around that explain why a single line of code needs to exist. I'm having trouble figuring out a way to get rid of these. They often follow this kind of structure:
// Needs to start disabled to avoid artifacts the first frame. Will enable after frame complete.
lineRenderer.enabled = false;
Then later on in the code I enable it.
I've thought about extracting it into a one-line method called StartLineRendererDisabledToAvoidArtifactsFirstFrame()
but this doesn't seem all that clean to me.
Are there any best practices for dealing with such one-liners? Many of them explain the existence of code that on the surface looks superfluous but then actually has an important function. I want to guard against future deletion.
Sidenote: I've already run into some scenarios where refactoring/renaming has made these comments be out-of-date or in the wrong spot etc. so I definitely see why removing them would be useful.
Related but different question here:
EDIT BASED ON ANSWERS AND COMMENTS BELOW
Here's my takeaway from all the great discussion below.
- Comments are fine if there's not an easy way to refactor/rename for more clarity. But they should be used sparingly.
- Removing comments is generally a good thing. But some comments need to exist to help future readers understand the code without having to dig too deep.
- But they should explain the WHY, not the HOW.
- If the code is there for a particular reason that is very important or fixes a bug, it should probably also have a corresponding unit test anyway.
- Commit messages can help track why and where and how the commented code came to be.