tl;dr– Comments themselves can be good! However, comments shouldn't be relied on to enforce program structure when the code could do this more reliably.
###It's unnecessarily relying on comments as a substitute for program structure that can be bad.
read that comments are almost always a bad idea for future maintainability.
They probably meant that relying on comments being read-and-understood is a bad idea for future maintainability.
###Example: Ensuring that a lineRenderer is re-enabled properly.
For example, adapted from the question statement:
/// Needs to start disabled to avoid artifacts in the first frame.
/// Must be re-enabled after the frame completes.
lineRenderer.enabled = false;
This is useful information, but relying on maintainers to always keep track of miscellaneous requirements like this without ever dropping the ball would seem hazard-prone.
The comment isn't the problem, but rather a symptom – someone put it there because they foresaw a potential problem and they're hoping that the comment prevents it from happening.
So the comment's good, just relying on it alone, rather than creating a logical structure, would be a bad idea for future maintainability.
For example, in C#, we might do something like this:
/// We assume that the line renderer is currently enabled.
/// It must be disabled for the first frame to avoid artifacts.
/// It must be re-enabled after the first frame.
if (!lineRenderer.Enabled)
{
throw new Exception(
"Error: The line renderer was already disabled,"
+ " in contradiction to the assumption that it should"
+ " have been enabled at this point."
);
}
try
{
lineRenderer.Enabled = false;
this.RenderFirstFrame();
}
finally
{
lineRenderer.Enabled = true;
}
The initial check ensures that lineRenderer is enabled, as our logic assumes this to be true.
The try{}finally{} ensures that lineRenderer is re-enabled even if it throws, assuming that the thrown Exception is caught. This way, if a thrown Exception is caught higher up the call-stack, the catcher isn't responsible stuff like re-enabling lineRenderer.
###Conclusion
In short, the point's that comments themselves aren't bad; it's relying on comments to enforce program logic that can be an issue for future maintainability.