Code separators and headers are more than a matter of style
IDontCareIfYouPreferPascalCase, ifCamelCaseIsForYou, or_if_you_prefer_lowercase_underscores. They all have their merits. However, there is one element of many style guides that I have come to vehemently disagree with: function/class headers* and separators. I bring it up because I’ve encountered them in pretty much every codebase I’ve worked with, but never found it difficult to convince people to stop using them.
Many people have the belief that there’s no inherent superiority between having and not having headers and separators. Separators vs. no separators is like PascalCase vs. camelCase. “It’s just the way it is, follow the guide, be consistent.”
It’s a reasonable opinion, but wrong.
Headers and separators are more like the comments that say #Open the file directly above the line that says with open(somepath) as f. Or more likely, a comment that says #Don't write the file yet above the line that says requests.get(someurl). Wait, what does that comment refer to? No idea, because someone edited the code but not the comment.
We’ve known these sorts of comments are harmful for a long time. They involve out-of-band, redundant information that quickly rots. Having to create purely formal, redundant information (“a new function becomes here!”) is extra work that cannot be justified. Headers and separators are the same. “Added missing separator above function” is a commit message no one should ever have to write or read. Separators and headers are not a debate about readability. They are harmful because they are an impediment to changing code.
Please, if you use separators and headers, stop it immediately, or at least listen to the next jerk that comes in and wants to stop using them.
* : I am also against file headers, but I know they can be useful in some cases, such as when your code is mingled with client code and it can be important for people to know what code came from where. I can tolerate overhead that has a demonstrable benefit.
Hi there. Let me contribute to the topic a little.
The header-style-comments debate in Python can be solved from a different angle. In Python, you have two types of comments for the purposes you stated in your entry: normal comments and docstrings.
Docstrings can accomplish (and should) the hsc separation intended by users who defend the use of them.
PEP8 specifies “Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.”.
PEP8 is not gods predicament, but is a good starting point to solve debate because it has a strong support in the Python community.
The usage of docstrings to document modules and classes should be sufficient to create the visual separation liked by hsc enthusiasts. It also follows a broad convention and can be used to create effective documentation for your module.
Good point by the anonymous poster.
If you have a problem with comment rot, why not change your definition of done? Code works? great. But it’s not done: make sure comments/headers get updated too -> done! Other things in the definition of done for code: e.g. descriptive variable names, unit tests (if appropriate), etc.
In the end you really have to weigh one versus the other: minimum comments, avoidance of rot vs. more comments/docstrings and time to maintain them. Pick whatever gives your team the greater benefit, depending on your team’s experience and skill and the code base you’re dealing with. I don’t think there’s a one-fits-all solution, even though I think you have good intentions by giving us this advice :)