Good code comments are important for software maintenance. This talk
goes beyond the common wisdom you find in most books and online and
explains when this common wisdom falls short.
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.
none
Python Skill Level:none
Domains:Code-Review
Link to talk slides:https://sschwarzer.com/download/comments_proposal_mindmap_pycon_de2019.pdf
Abstract as a tweet:Good code comments are important for software maintenance. This talk goes beyond the common wisdom you find in most books and online and explains when this common wisdom falls short.