I'm convinced that good code comments are very important for software maintainability.

But how do we achieve good comments?

Doing a web search on code comments yields some "common wisdom". Here are three examples:

• Comments should describe the "Why", not the "What".

• Extract functions/methods instead of commenting code sections inside a function/method.

• Use better names instead of writing comments.

• ...

The talk adds more context to such claims to show when they apply and when not. For example, you could understand a code section by reading it carefully, but a summary comment can make this a lot easier, although such a comment is a "what comment" rather than a "why comment."

How much commenting is needed doesn't depend on the code alone. As the talk discusses, this depends on the experience of the team members and their fluctuation. Note that "experience" is much more complex than you may think. For example, the term can apply to general programming experience, domain knowledge - or several other aspects of "experience."

An important part of the talk is how to comment in order to help readers of the code. As one example, add comments on things you learned while writing the code.

Stefan Schwarzer

Affiliation: SSchwarzer.com

Stefan has been using Python professionally for more than 15 years, the last 10+ years as a freelancing software developer and consultant (https://sschwarzer.com/en/). He has published articles on Python and given talks on Python at several conferences. He's also the maintainer of the ftputil library (https://pypi.org/project/ftputil/).

visit the speaker at: Homepage