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*

5
  • 2
    I'm not convinced by the assertion that function names are more likely to keep track of reality than comments. I've seen plenty of functions whose behaviour is completely at odds with their name, because developers were too afraid of the impact of renaming. In some cases, you can't rename a function, because it's part of a stable library contract, whereas I've yet to see a case where you can't edit a comment once you realise it's wrong. Commented May 15, 2020 at 9:36
  • 1
    @IMSoP, I think to be fair to him, his emphasis is that comments will either be overlooked for maintenance, or that subsequent maintenance developers are often unsure how to evaluate their accuracy or truthfulness. Since the placement and conceptual content of comments often does not conform to any structure, and are not subject to tests, the reliability of comments may be highly questionable. Commented May 15, 2020 at 10:44
  • @Steve Everything you just said applies to function names too; they don't mean anything to the compiler or the testing framework, it needs a developer to think about what they mean in human language and decide if they're still correct or not. Commented May 15, 2020 at 11:30
  • @IMSoP, potentially so. It's a difficult issue because I don't agree with him that names should basically be turned into comments (so I don't agree with his proposed solution), but I do agree that comments are prone to be crufty (his description of the problem). If names are more likely to track reality, then in my view this is because they are short, and usually subject to considered design and review, whereas comments are often vague and unstructured expressions of individual developers' thoughts. Commented May 15, 2020 at 12:49
  • 1
    @Steve Yes, I think that's a reasonable way of putting it. As I commented under another answer, it's no good just converting your comment into a name and saying you're done, you've got to address why the code is so complex that you need a long name or comment in the first place. Commented May 15, 2020 at 13:16