News for hackers. Stuff that matters.
Re:Writing system software: code comments by BonesJustice on Sunday October 07, 2018 @06:59PM (#18163083)
Well said. Particularly in highly optimized code, it can save future maintainers (e.g., you) precious time if you take a moment to explain the things that are not obvious and could, at first blush, look like bugs.

Writing good comments requires a lot of vigilance: not only do you need to know which decisions to explain, but good documentation often entails explaining why you didn’t do something.

“We don’t need a memory barrier here because ____.”

“There is a subtle race between X and Y here, but it’s benign because ____.”

Of course, if your colleagues are not as disciplined as you, even the best comments can fall victim to comment rot over time.

There are no comments on this comment yet.