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.
“To comment or not to
comment?”
A data-driven look at conflicting attitudes towards
commenting and documentation.
@veronic...
@veronica_hanus #PyTexas2019
Critique the comments!
Why document?
@veronica_hanus #PyTexas2019
Comments as first documentation
Purpose of comments:
➔ Summary: authorship, purpose
➔ Describe functions
➔ Clearify “trick...
Confusion about comments
@veronica_hanus #PyTexas2019
And then we debate
@veronica_hanus #PyTexas2019
Best practices we can get behind
Code tells how,
comments tell why
Don’t Waste
Everyone’s Time
(WET)
Line-by-line show lac...
Design has methods
& tools!
Let’s face it… comments are magic
Comments can:
- Label
- Store questions
- Notes to research
...
Good code is DRY
We hear...Advice
The way you learn
is an antipattern!
- Refactor
- Code better
- Don’t use comments
- Use...
Short answer:
- Current/recent use: Comment uncertainty, Function-
level comments, Clarification, Unused code, Other
- Whe...
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
@veronica_hanus #PyTexas2019
Scoping
Experiment
Completing program
Pairing/learning
When others
misunderstand
@veronica_hanus #PyTexas2019
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
Not certain
Each function
In-line
Unused code
@veronica_hanus #PyTexas2019
@veronica_hanus #PyTexas2019
The best use of comments
@veronica_hanus #PyTexas2019
What can we do?
Goal: Support learners where they are at, praising their
accomplishments, while pointing them gently towar...
Thanks to…
Each of you (!), PyTexas for
having me, & the ~170
internet-folk who have shared
their stories <3
Please tell y...
Learning resources
- Docs that drive code: https://blog.izs.me/2017/06/documentation-driven-development
- Readmes (start h...
Credits
- ASCII comments: https://twitter.com/johnregehr/status/1095018518737637376
- “Suffering on StackOverflow”: https:...
Upcoming SlideShare
Loading in …5
×

To comment or not to comment?

47 views

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 PyTexas 2019 in Austin.
Event link: https://www.pytexas.org/2019/talk/U2Vzc2lvbk5vZGU6OTQ=

Published in: Software
  • Be the first to comment

  • Be the first to like this

To comment or not to comment?

  1. 1. “To comment or not to comment?” A data-driven look at conflicting attitudes towards commenting and documentation. @veronica_hanus #PyTexas2019
  2. 2. @veronica_hanus #PyTexas2019 Critique the comments!
  3. 3. Why document? @veronica_hanus #PyTexas2019
  4. 4. Comments as 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 #PyTexas2019
  5. 5. Confusion about comments @veronica_hanus #PyTexas2019
  6. 6. And then we debate @veronica_hanus #PyTexas2019
  7. 7. Best practices we can get behind Code tells how, comments tell 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 #PyTexas2019
  8. 8. Design has methods & tools! Let’s face it… comments are magic Comments can: - Label - Store questions - Notes to research - Code outline - Storage for unused code - References/credit @veronica_hanus #PyTexas2019
  9. 9. Good code is DRY We hear...Advice The way you learn is an antipattern! - Refactor - Code better - Don’t use comments - Use only the right comments - Only code matters @veronica_hanus #PyTexas2019
  10. 10. Short answer: - 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: - Comments: - Help me remember what my code does - Clarify my thinking - Help me learn - Save time - Delete before projects is shared - Uncomfortable writing - Yes to function-level, no in-line - Clear code is self-documenting Conflicting results & looking deeper @veronica_hanus #PyTexas2019
  11. 11. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  12. 12. @veronica_hanus #PyTexas2019
  13. 13. Scoping Experiment Completing program Pairing/learning When others misunderstand @veronica_hanus #PyTexas2019
  14. 14. @veronica_hanus #PyTexas2019
  15. 15. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  16. 16. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  17. 17. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  18. 18. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  19. 19. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  20. 20. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  21. 21. Not certain Each function In-line Unused code @veronica_hanus #PyTexas2019
  22. 22. @veronica_hanus #PyTexas2019
  23. 23. The best use of comments @veronica_hanus #PyTexas2019
  24. 24. 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! ➔ 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? @veronica_hanus #PyTexas2019
  25. 25. Thanks to… Each of you (!), PyTexas for having me, & the ~170 internet-folk who have shared their stories <3 Please tell your friends, coworkers, & that person at work who thinks docs are a waste of time but DO NOT respond after this talk! (5 min survey) http://bit.ly/comment-use @veronica_hanus #PyTexas2019
  26. 26. Learning resources - Docs that drive code: https://blog.izs.me/2017/06/documentation-driven-development - Readmes (start here!): http://tom.preston-werner.com/2010/08/23/readme-driven-development.html - My post on Readme mechanics : http://veronicahanus.com/blog/2017/03/06/writing-readmes.html - Docs are part of code: https://www.writethedocs.org/guide/docs-as-code/ - Motivation for docs: https://stoplight.io/blog/writing-documentation-when-you-arent-a-technical-writer-part- two-59997587cc2a/ - Guideline for docs: https://opensource.com/business/15/5/write-better-docs - Read code? Read docs too! (& resources for doc generation): https://github.com/PharkMillups/beautiful-docs - Goal of documentation: https://kadavy.net/blog/posts/productivity-cycles-podcast/ - Talks from “Compassionate Coding”: https://compassionatecoding.com/media - Notes from a deep dive into “Clean Code”: https://medium.com/mindorks/how-to-write-clean- code-lessons-learnt-from-the-clean-code-robert-c-martin-9ffc7aef870c - Guidelines for comments: https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html @veronica_hanus #PyTexas2019
  27. 27. Credits - ASCII comments: https://twitter.com/johnregehr/status/1095018518737637376 - “Suffering on StackOverflow”: https://medium.com/@Aprilw/suffering-on-stack-overflow- c46414a34a52 - We all go through this: https://twitter.com/anupbattasha/status/1094959013194649600 - Comment your cats: https://twitter.com/carterwickstrom/status/1014165500056596481 - Commenting for learning: https://twitter.com/jessfraz/status/1093713454781784065 - Man pages for documentation: https://twitter.com/aemeredith/status/1033445823181287424 - Goal of documentation: https://twitter.com/kadavy/status/1093820499271000064 @veronica_hanus #PyTexas2019

×