To #comment or not? A data-driven look at...

on YouTube ↗05m

" summary

Data-driven claim: a survey of 170 respondents (scraped/web survey) finds surprising practices and contradictions—60% use inline comments despite norms against them, 63% use comments to explore new ideas, and 78% reject aggressive “no comments” attitudes. The talk reports the scraping and survey method, quantified results, examples of confusing comments, and suggestions about tooling and norms that aim to preserve learners’ scaffolding while reducing noisy, unhelpful commentary.

AI-written summary · about

" chapters (4)

1. 0:00Start
2. 0:42Comments as a learner's first documentation Purpose of comments: → Summaryauthorship, purpose Describe functions
3. 1:12Best practices we can (usually) get behind Always Docstrings should
4. 4:27What can we do? → Remember our overwhelmed learner → Advise current them, not future them! → Suggest a deep dive & reading others' code?

" related talks

• 41mTo comment or notVeronica Hanus · PyData New York City 2019
• 13mOn Readable CodeJared Wyles · Web Directions Code 2014
• 21mThe Art of Code CommentsSarah Drasner · JSConf Hawaiʻi 2020
• 24m//TODO: Write A Better CommentAdam McNeilly · droidcon NYC 2019
• 15mElevating Pull Requests: The Role of Conventional CommentsMouleeswaran Ganapathi · Devoxx France 2024
• 09mFostering a learning culture in coding teamsCat Hicks · It Will Never Work in Theory (Online, April 2022)
• 07mState of the commentsArthur Schiwon · Nextcloud Conference 2016
• 18mHow To Review Someone's Code While Not Being A Jerk!Maha Alsayasneh · DevFest Toulouse 2023