To comment or not? A data-driven look at attitudes toward code comments

How can someone who is just learning find the commenting style that is best for them as they learn, grow, & contribute? I did a survey of programmers & will be sharing what we can do to address comment use in a way that encourages a growth mindset and empowers everyone.

Every programmer has asked themselves “how many comments are too many?” To the newest programmers, comments may seem magical–a way of documenting without giving instructions to the computer. But commenting engages the same vulnerability as more advanced challenges (i.e. pair programming & code review) and is likely to pique the insecurity of many programmers (especially the copy-and-paste or tutorial-level programmer)!

While most of us agree that commenting is part of writing maintainable code, it’s very difficult for someone who has not yet worked in a community-reviewed codebase to know what is good practice and not. The answers that come back often conflict each other: Code should be DRY, but well-placed comments save future devs. How can someone find the commenting style that is best for them as they learn, grow, & contribute? My survey of 170 long-time developers, Computer Science majors, bootcamp grads, & hobby programmers confirms some expectations and brings others into question. Join me for a data-based chat about the biggest pain points caused by our attitudes toward commenting and the steps we can take to encourage a growth mindset and empower programmers of all levels.

Experience with this talk

This talk has been given at DjangoCon US, SciPy US, PyCon Australia, PyCon Czech Republic, PyTexas, PyCascades, PyTennessee, the Flatiron School (“lunch and learn”), DevOpsDays Chicago, PyGotham NYC, and at meetups in Santo Domingo and New York City.

Outline

Speaker intro

• Python + web, forever-learner & member of several “new programmer” communities, workshop giver
• Self-taught programmer, always curious about documentation and comments
• Former scientist & forever data enthusiast

Statement of problem

• Programmers at every level are interested in “best practices,” but new learners are especially driven to learn and follow them. They want to write the best code they can, as quickly as they can. Without the experience to know the “why” for our “rules,” they can fall into the great toxic pitfalls of newbie programming: “just tell me how to do it” & decision paralysis.
• Questions about commenting are often asked in a way that invites a binary answer: “how many comments are too much?” suggests that there might be a set “too much”. While most experienced programmers are happy to discuss the nuance of “when to comment”, a number of inexperienced programmers have heard “good code is dry” and being exposed to this binary can cause a lot of anxiety. (share examples of this)
• After seeing so many conflicting viewpoints and seeing how many other developers had similar concerns, I decided to start collecting data to examine the problem

Experiments - Different Types of Comments

• As beginners learn about commenting and seek the right documenting style, they experiment and innovate. While most of us would grimace to see these in a codebase, we should take a moment to appreciate the problem-solving they show
• Commenting styles
• Comments to plan
  • For me, this was transition between tutorials & personal projects
  • “Comment-driven development”
• Line-by-line comments
• In “Codecademy phase”, I commented every line I wrote to make sure I understood what I was writing. Later, I even added links to any Stack Overflow or docs I had found helpful b/c struggled to find the right keywords / google effectively. I wanted to be able to review my resources and I wanted people seeing my code to understand how much was “mine” (Sometimes learners have to be “selfish” and comment for themselves!)
• Function-level comments (Docstrings)
• Getting into an area that few people will argue with
• In-line clarification (variables, etc.)
• So now, we’ve established some empathy & seen how one may adapted different styles to solve their pain-points
• How can we most helpfully direct the eager beginner?

Data Collection & Analysis - Survey on Comment Use

• I explored the questions that had given the most interesting results in my conversions
• My questions are below:
• Short answer:
• Current/recent use: Comment uncertainty, Function-level comments, Clarification, Unused code, Other
• When comments added: Scoping & planning, As functions written, Pairing, As I learn people don’t understand, Clean-up
• How long programming?
• How long professionally?
• Path to programming?
• Agree/Disagree:
• Comments:
• Help me remember what my code does
• Clarify my thinking
• Help me learn
• Save time
• Delete before projects is shared
• Uncomfortable writing
• Yes to function-level, no in-line
• Clear code is self-documenting
• Participants were recruited from forums that cater to individuals at a variety of skill levels without any introduction on the questions being tested

Data - Survey results

• Clear that “clean code doesn’t need comments” is all over the board while other response clusters around being strongly pro-comment

Shifting to a growth mindset

• Validate the learning process when discussing best practices
• Empathy + supporting learning + empowering to consider many ideas » being right
• Discuss nuance of a person’s current practice and discuss alternatives / what may be coming next for them

Wrap up