Code separators and headers are more than a matter of styleby Rob Galanakis on 4/08/2014
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 email@example.com