To comment or not to comment? Conflicting attitudes towards commenting and beginner pain.
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 beginning programmers.
- Python + web, forever-learner & member of several “new programmer” communities, workshop giver
- Interested in how commonly “how many comments are too many” is asked by newer programers & started to think about how “dry” code might not be the best for learning
Statement of problem
- New learners quickly become interested in “best practices”. 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.
The nuanced answer
- Examples of commenting styles & when each is helpful
- All this is colored by my programming journey: Line-by-line tutorials (eg. Codecademy), Broadly outlined projects (eg. Boston Python Women’s Workshop), Lots of learning motivated by but unconnected to projects (eg. best practices: modular code, …), Individual (unguided) projects (eg. HTML/CSS website), Contributing to other’s work
- Comments to plan
- “Comment-driven development”
- Line-by-line comments
- Function-level comments (Docstrings)
- In-line clarification (variables, etc.)
What can we do?
- 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
- Type: talk
- Expected length: 30min
- Intended audience: Beginner
About the Author