To comment or not to comment? Conflicting attitudes towards commenting and beginner pain.

Abstract

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.

Talk Description

Every programmer has asked themselves at least once “how many comments are too many?” To the newest programmers, comments seem magical - a way of talking to yourself (or someone else!) without giving instructions to the computer. But commenting is a form of documentation/communication and engages the same vulnerability as later challenges (eg. 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 some level of commenting is part of writing maintainable code, it’s very difficult for someone who has not yet worked in someone else’s 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? I did a survey of long-time industry folks, CS-majors, bootcamp grads, & hobby programmers, and I’ll be presenting my results (a few surprises here!) & sharing what we can do to address questions about comment-use in a way that encourages a growth mindset and empowers all of us.

About the Talk

About the Author

Before Veronica was a programmer, she was a researcher (she helped pick the Mars Curiosity Rover’s landing site!) with an eye for process improvement. As she’s taught herself web development, she’s brought her research approach from her time at NASA-JPL & MIT into whatever she was learning. She loves exploring the web and teaching, and recently co-taught a PyCon tutorial on using web-scraping and modeling to predict Oscar winners. When she isn’t learning how the web can be better for developers, she enjoys blogging, nerding out about documentation, and snuggling as many cats as possible.