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.

5
  • 5
    "Since any IDE will render comments in a different colour, having a blank line and a single short comment at the top of a block of code can help the eye spot the logical sections." So would whitespace, and that would be easier to write, maintain, and navigate by cursor. Commented Jun 13, 2024 at 4:26
  • 1
    @Flater "So would whitespace" - well, yes, that's why I explicitly said "a blank line and a short comment". Providing visual cues - including both whitespace and comments - is a useful technique for improving code readability, even if the question is a terrible example of how to do that correctly. Commented Jun 14, 2024 at 0:31
  • As an example, I typically separate sections of code in my file with 5 lines. In order: a blank line, a comment line with no text, a comment line with the section title, a comment line with no text, and another blank line. This is lightweight to maintain, and pops out sufficiently in the file outline in the IDE to quickly jump from section to section. Commented Jun 15, 2024 at 10:36
  • @MatthieuM. That's a bit too much whitespace for my taste - in general I wouldn't want more than one blank line and one comment - but not unreasonable. Commented Jun 16, 2024 at 20:41
  • @SimonGeard: I think it depends what you're commenting for. As I mentioned I use those 5 lines as "section separators", and my files typically have only one such separator (between the public section first, and the implementation section second), so 5 lines is fine... and really helps pinpointing it in the outline. For doc comments on methods, I don't "waste" lines. Commented Jun 17, 2024 at 7:48