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 :)

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.