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

Tuesday 5:00 pm to 5:30 pm, in Salon A-E

About This Talk

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.


    Photo of

    Veronica Hanus

    Before becoming a programmer, Veronica was a researcher with an eye for process improvement (she helped pick the Mars Curiosity Rover’s landing site!). She loves exploring the web and teaching, and speaks on building the tooling & docs you need and has co-taught a PyCon tutorial on using web-scraping and machine learning to predict Oscar winners. When she isn’t thinking about how the web can be better for developers, she enjoys blogging and snuggling as many cats as possible.

    Past speaking experience:

    Technical presentations

    • “To comment or not to comment? Conflicting attitudes towards commenting and beginner pain” (this talk), Flatiron NYC (March, 2019)
    • “Git ‘Hooked’ on images in your version control and up your documentation game”, Git Merge (Belgium, Feb. 2019), PyTennessee (Feb. 2019), PyCaribbean (Feb. 2019)
    • Workshop on “Git ‘Hooked’ on images in your version control and up your documentation”, Flatiron NYC (Jan. 2019)
    • “Imagining Colors is Hard: Representing Visual Changes in Version Control”, Hacktoberfest NYC 2018 slides
    • Assisted in teaching “Lights Camera Action! Scrape, explore, and model to predict Oscar winners & box office hits” tutorial at PyCon 2018 description bio video materials
    • “Using Unix to make your time in the terminal better” at NYC Women’s Work Jelly 2017 project page
    • Assisted in teaching “Python for Data Science” tutorial at Boston Code Camp 27 (2016) description materials
    • “Giving Imposter Syndrome the Kick in the Pants It Deserves” at NYC Women’s Work Jelly 2016 slides
    • Workshop “LaTeX: Academic Typesetting for Industry” at Recurse Center 2015 materials

    Teaching experience

    • SAT Writing Instructor for MIT Academic Teaching Initiative 2011-2012 Developed & taught 12-week SAT Writing course • Median 50% showed a 200 point increase during the course • A few students even contacted me as they were writing college entrance essays

    • Programming Coach for Bootstrap Afterschool Program 2011-2012 Provided 1-on-1 and group instruction for 14 middle-school students in creating their own games • Used functional programming (Scheme) and pair programming to teach algebraic concepts (Pythagorean theorem & writing appropriate algebraic functions) and programming concepts (problem solving using the Design Recipe, data types, Boolean logic, conditional branching, functions & variables)

    Research-related presentations/communication

    • Presented findings of safety tests of malfunctioning equipment to lab at MIT Paleomagnetism Laboratory 2012
    • Presented findings to internal committee / communicated intern project needs to software developer at NASA JPL 2009 • Led student effort to find rock distributions of landing sites for Curiosity rover • Introduced three students to in-house software for QA element of our project, including reporting procedures, and software process and limitations