Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

18
  • 6
    Disagree with a given example - instead of writing many comments in one huge function, you should compose it from many smaller functions with descriptive names, that will act as comments. Without a risk of being out of sync with what the code is really doing. Commented Mar 8, 2018 at 14:06
  • 6
    Finally some sanity. Extracting every piece of code that could use a comment into its own function is how you end up with thousands of functions spread across hundreds of files. Commented Mar 8, 2018 at 15:45
  • 2
    That second example is lovely. Commented Mar 8, 2018 at 19:20
  • 7
    The comments in the second example are much too verbose. Some of them (e.g. "Did we find anything?") just repeat what the code says and would be better removed. For other, you could gain more readability by refactoring, like making (stream.is_empty()) the loop condition, or moving the check for accept_literals outside. Commented Mar 8, 2018 at 20:10
  • 3
    @cpburnz, "I've had to dig through too many legacy projects and third-party libraries without any code comments to appreciate comments that explain what's happening and why". exactly my point all along: comments are there to explain crap code. Since the question is "how do I write code that easy to read" then clearly this answer is wrong as it focuses on writing comments to explain bad code, rather than writing good code in the first place. Commented Mar 9, 2018 at 9:16