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*

19
  • 15
    I agree with all your point, except that comments do have their place. While I agree there's no point in comments like add 1 to i, comments should explain why the code does what it does. For example, the code if (!something.Exists()) {...} can use a comment like: // something exists only when (explanation of the broader scenario). Commented Mar 8, 2018 at 12:58
  • 17
    We've all seen our fair share of // increment x x++; comments that are of no use, but it's wrong to throw the baby out with the bathwater and declare that comments are always bad. For example, comments of the form // this case should never happen because xyz throw exception "unreachable". Commented Mar 8, 2018 at 14:48
  • 7
    Very nice list. But like @Jonathan. I do not agree with the comments. Some times you have to account for bugs in a third party frameworks though. While this can be refactored into its own function it's still nice to leave a bit of description to why the workaround (bugnumber or bugname/description of the bug) is required. Commented Mar 8, 2018 at 16:34
  • 17
    @DavidArno But you cannot do that for a comment explaining why something was not done. Like //XXX: Not using straight-forward method Foo here because .... Such comments can be immensely valuable, but are impossible to convey with code for obvious reasons. Commented Mar 8, 2018 at 16:37
  • 7
    I like it even more dramatic: every comment is a failure to express yourself well in code. For example, I have a 4 line comment in one method, explaining the workaround for a 3rd party bug. I failed to express that well in code, so it's in a comment. I'd say it improved readability tough, because I doubt anybody would enjoy scrolling horizontally to read a very long and very descriptive method name. "Comments are a code smell" - yes, but we have to remember that not everything that smells is sh*t. Commented Mar 8, 2018 at 18:18