Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

PyGotham 2019 "To comment or not to comment?"


Published on

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.

This talk was given at PyGotham in NYC in Oct 2019.
Event link:

Published in: Software
  • Be the first to comment

  • Be the first to like this

PyGotham 2019 "To comment or not to comment?"

  1. 1. A data-driven look at conflicting attitudes towards commenting and documentation. @veronica_hanus #PyGotham
  2. 2. @veronica_hanus
  3. 3. Comments as a learner’s first documentation Purpose of comments: ➔ Summary: authorship, purpose ➔ Describe functions ➔ Clearify “tricky code”/unclear decisions Allowing: ➔ Easier stand-alone doc-writing! ➔ A “notepad” ➔ Tell why! @veronica_hanus
  4. 4. Comments get a pretty bad rep! @veronica_hanus
  5. 5. When does refactoring happen? ➔ New work > refactoring ➔ Time for feedback? ➔ Feel like a “nice to have” Refactor when…. ➔ Can’t stand it anymore ➔ Problem grows Refactoring == self-care?? @veronica_hanus
  6. 6. Finally! Time to refactor! @veronica_hanus
  7. 7. @veronica_hanus
  8. 8. @veronica_hanus Don’t Repeat Yourself! Keep it D.R.Y.! Undocumented code is unusable!
  9. 9. @veronica_hanus
  10. 10. @veronica_hanus
  11. 11. @veronica_hanus
  12. 12. Best practices we can (usually) get behind Code is the “how”, comments are the “why” Don’t Waste Everyone’s Time (WET) Line-by-line show lack of understanding Docstrings should have inputs, outputs, transformation Outdated comments == lies Too much is too much Always! Maybe? @veronica_hanus
  13. 13. @veronica_hanus
  14. 14. @veronica_hanus
  15. 15. @veronica_hanus “JUST CODE BETTER”Thanks, people of the Internet!
  16. 16. @veronica_hanus [Subtext] HEY Newbie! Your struggle BORES ME & shows you are a bad programmer! KTHXBYE
  17. 17. Design has methods & tools! Let’s face it… comments are magic @veronica_hanus
  18. 18. @veronica_hanus
  19. 19. Comments can: - Label - Questions - Notes - Outline - Storage - References - Support overwhelmed learners @veronica_hanus
  20. 20. @veronica_hanus # V!: TODO [........] # Veronica was heree! Move fast & break things write bad comments
  21. 21. @veronica_hanus
  22. 22. @veronica_hanus
  23. 23. @veronica_hanus
  24. 24. @veronica_hanus
  25. 25. Radial: - 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 (1-10): - Comments: - Help me remember what my code does - Clarify my thinking - Help me learn - Save time - Delete before projects is shared - Yes to function-level, no in-line - Clear code is self-documenting - Uncomfortable writing @veronica_hanus
  26. 26. Not certain Each function In-line Unused code @veronica_hanus
  27. 27. Scoping Experiment Completing program Pairing/learning When others misunderstand @veronica_hanus
  28. 28. Not certain Each function In-line Unused code @veronica_hanus
  29. 29. Not certain Each function In-line Unused code @veronica_hanus
  30. 30. Not certain Each function In-line Unused code @veronica_hanus
  31. 31. Not certain Each function In-line Unused code @veronica_hanus
  32. 32. Not certain Each function In-line Unused code @veronica_hanus
  33. 33. Not certain Each function In-line Unused code @veronica_hanus
  34. 34. @veronica_hanusMake your own!
  35. 35. “A global patchwork of Github & Gitlab repositories don’t just contain software--they contain our shared understanding & collaboration around common interests & problem solving.” Jono Bacon in his forward to “The Business Value of Developer Relations” @veronica_hanus
  36. 36. Comments teach us about ourselves @veronica_hanus
  37. 37. What can we do? Goal: Support learners where they are at, praising their accomplishments, while pointing them gently toward the future ➔ Empathy can be hard! ➔ Remember our overwhelmed learner ➔ Advise current them, not future them! ➔ Write w/ comments? Share them! ➔ Suggest a deep dive & reading others’ code? What can we say? What do they need? ➔ Someone is learning their attitudes toward documentation from you Rethink comments ➔ Comments == docs? ➔ Comments teach us about ourselves @veronica_hanus
  38. 38. 👇Your company recruiting a DevRel or Dev Advocate?👇 🙌@veronica_hanus🙌 🙏 Each of you for coming, the PyGotham organizing team for the opportunity, & the ~170 internet-folk who have shared their “comments on comments” <3 I tweet at @veronica_hanus Non-tweeters 👋 Survey: Video & Slides 🔜 🙌Write the comments you wish you had!
  39. 39. Learning resources - Docs that drive code: - Readmes (start here!): - My post on Readme mechanics : - Docs are part of code: - Motivation for docs: - Guideline for docs: - Read code? Read docs too! (& resources for doc generation): - Goal of documentation: - Talks from “Compassionate Coding”: - Notes from a deep dive into “Clean Code”: ef870c - Guidelines for comments: @veronica_hanus
  40. 40. Credits - ASCII comments: - “Suffering on StackOverflow”: - We all go through this: - Comment your cats: - Commenting for learning: - Man pages for documentation: - Goal of documentation: - Programmer in bath: - A good programmer: - Squirrels wants you to stop: - Sad programmer: - Inconceivable: @veronica_hanus
  41. 41. Not certain Each function In-line Unused code @veronica_hanus
  42. 42. @veronica_hanus
  43. 43. @veronica_hanus
  44. 44. @veronica_hanus