SlideShare a Scribd company logo
1 of 46
Download to read offline
A data-driven look at
conflicting attitudes towards
commenting and documentation.
@veronica_hanus #PyGotham
@veronica_hanus
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
Comments get a pretty bad rep!
@veronica_hanus
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
Finally! Time to refactor!
@veronica_hanus
@veronica_hanus
@veronica_hanus
Don’t Repeat Yourself!
Keep it D.R.Y.!
Undocumented
code is unusable!
@veronica_hanus
@veronica_hanus
@veronica_hanus
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
@veronica_hanus
@veronica_hanus
@veronica_hanus
“JUST CODE
BETTER”Thanks, people of the Internet!
@veronica_hanus
[Subtext] HEY Newbie! Your
struggle BORES ME & shows
you are a bad programmer!
KTHXBYE
Design has methods
& tools!
Let’s face it… comments are magic
@veronica_hanus
@veronica_hanus
Comments can:
- Label
- Questions
- Notes
- Outline
- Storage
- References
- Support
overwhelmed
learners
@veronica_hanus
@veronica_hanus
# V!: TODO
[........] # Veronica
was heree!
Move fast & break things
write bad comments
@veronica_hanus
@veronica_hanus
@veronica_hanus
@veronica_hanus
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
Not certain
Each function
In-line
Unused code
@veronica_hanus
Scoping
Experiment
Completing program
Pairing/learning
When others
misunderstand
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
@veronica_hanusMake your own! https://www.ascii-art-generator.org/
“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
Comments
teach us about
ourselves
@veronica_hanus
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
👇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 👋me@veronicahanus.com
Survey: http://bit.ly/comment-use
Video & Slides 🔜
http://veronicahanus.com/talks
🙌Write the comments you wish you had!
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-9ffc7a
ef870c
- Guidelines for comments: https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html
@veronica_hanus
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
- Programmer in bath:
https://footage.framepool.com/en/shot/798293950-bath-tub-bathroom-information-technology-student-university
- A good programmer: https://code.likeagirl.io/herstory-software-engineer-maker-estefannie-d4fdec7b069a
- Squirrels wants you to stop:
https://patch.com/florida/brandon/stop-right-there-brandon-squirrel-wins-world-photo-contest
- Sad programmer:
https://drawception.com/game/H73GxcwzmW/a-sad-programmer-playing-drawception/#panel-1537906
- Inconceivable: https://images.app.goo.gl/2nnv4DN7E8yFkeKj8
@veronica_hanus
Not certain
Each function
In-line
Unused code
@veronica_hanus
@veronica_hanus
@veronica_hanus
@veronica_hanus

More Related Content

Similar to Conflicting attitudes towards commenting and documentation

44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...
44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...
44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...Daniel Doan
 
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCaster
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCasterAPIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCaster
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCasterapidays
 
Technical Writing meets Instructional Design
Technical Writing meets Instructional DesignTechnical Writing meets Instructional Design
Technical Writing meets Instructional DesignSharon Hamilton Jendrisak
 
Hidden sides of Code Review (Do-iOS)
Hidden sides of Code Review (Do-iOS)Hidden sides of Code Review (Do-iOS)
Hidden sides of Code Review (Do-iOS)Dmitrii Ivanov
 
How to Attract & Survive Media Attention as PhD
How to Attract & Survive Media Attention as PhDHow to Attract & Survive Media Attention as PhD
How to Attract & Survive Media Attention as PhDThomas Winters
 
This i Believe CATE2014 presentation
This i Believe CATE2014 presentationThis i Believe CATE2014 presentation
This i Believe CATE2014 presentationJanet Ilko
 
Career Hacks for Developers
Career Hacks for DevelopersCareer Hacks for Developers
Career Hacks for DevelopersBarElin
 
Getting into the tech field. what next
Getting into the tech field. what next Getting into the tech field. what next
Getting into the tech field. what next Tessa Mero
 
gettingintothetechfieldwhatnext-210526205624.pdf
gettingintothetechfieldwhatnext-210526205624.pdfgettingintothetechfieldwhatnext-210526205624.pdf
gettingintothetechfieldwhatnext-210526205624.pdfroystoncdsouza7
 
Getting to Senior in UX
Getting to Senior in UXGetting to Senior in UX
Getting to Senior in UXCyd Harrell
 
Nasdaq Pro/Design Masterclass at the Entrepreneurial Center
Nasdaq Pro/Design Masterclass at the Entrepreneurial CenterNasdaq Pro/Design Masterclass at the Entrepreneurial Center
Nasdaq Pro/Design Masterclass at the Entrepreneurial CenterChris Avore
 
Publishing 102 11 18
Publishing 102  11 18Publishing 102  11 18
Publishing 102 11 18Karen Brooks
 
Based Argumentative paper.docx
Based Argumentative paper.docxBased Argumentative paper.docx
Based Argumentative paper.docxwrite12
 
Phoenix Design Week: User Journeys for Damn Good Digital Design
Phoenix Design Week: User Journeys for Damn Good Digital DesignPhoenix Design Week: User Journeys for Damn Good Digital Design
Phoenix Design Week: User Journeys for Damn Good Digital DesignRebekah Baggs
 
Tenure track socialmedia_10082010
Tenure track socialmedia_10082010Tenure track socialmedia_10082010
Tenure track socialmedia_10082010Ines Mergel
 
Rich UX Research for Everyone
Rich UX Research for EveryoneRich UX Research for Everyone
Rich UX Research for EveryoneCyd Harrell
 
Content Strategy: Do It For Your Users
Content Strategy: Do It For Your UsersContent Strategy: Do It For Your Users
Content Strategy: Do It For Your UsersAndrea Sarther
 
Build Your Own Contributors, One Part At A Time
Build Your Own Contributors, One Part At A TimeBuild Your Own Contributors, One Part At A Time
Build Your Own Contributors, One Part At A Timedreamwidth
 
How to Create Content for SEO That Earns Me Links?
How to Create Content for SEO That Earns Me Links?How to Create Content for SEO That Earns Me Links?
How to Create Content for SEO That Earns Me Links?Digital Third Coast
 
Defying the itch to stitch
Defying the itch to stitchDefying the itch to stitch
Defying the itch to stitchstephtroeth
 

Similar to Conflicting attitudes towards commenting and documentation (20)

44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...
44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...
44 Common Copywriting Mistakes That Might Accidentally Kill Your Landing Page...
 
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCaster
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCasterAPIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCaster
APIdays Paris 2019 - Continuous Documentation by Kenigbolo Meya Stephen, BCaster
 
Technical Writing meets Instructional Design
Technical Writing meets Instructional DesignTechnical Writing meets Instructional Design
Technical Writing meets Instructional Design
 
Hidden sides of Code Review (Do-iOS)
Hidden sides of Code Review (Do-iOS)Hidden sides of Code Review (Do-iOS)
Hidden sides of Code Review (Do-iOS)
 
How to Attract & Survive Media Attention as PhD
How to Attract & Survive Media Attention as PhDHow to Attract & Survive Media Attention as PhD
How to Attract & Survive Media Attention as PhD
 
This i Believe CATE2014 presentation
This i Believe CATE2014 presentationThis i Believe CATE2014 presentation
This i Believe CATE2014 presentation
 
Career Hacks for Developers
Career Hacks for DevelopersCareer Hacks for Developers
Career Hacks for Developers
 
Getting into the tech field. what next
Getting into the tech field. what next Getting into the tech field. what next
Getting into the tech field. what next
 
gettingintothetechfieldwhatnext-210526205624.pdf
gettingintothetechfieldwhatnext-210526205624.pdfgettingintothetechfieldwhatnext-210526205624.pdf
gettingintothetechfieldwhatnext-210526205624.pdf
 
Getting to Senior in UX
Getting to Senior in UXGetting to Senior in UX
Getting to Senior in UX
 
Nasdaq Pro/Design Masterclass at the Entrepreneurial Center
Nasdaq Pro/Design Masterclass at the Entrepreneurial CenterNasdaq Pro/Design Masterclass at the Entrepreneurial Center
Nasdaq Pro/Design Masterclass at the Entrepreneurial Center
 
Publishing 102 11 18
Publishing 102  11 18Publishing 102  11 18
Publishing 102 11 18
 
Based Argumentative paper.docx
Based Argumentative paper.docxBased Argumentative paper.docx
Based Argumentative paper.docx
 
Phoenix Design Week: User Journeys for Damn Good Digital Design
Phoenix Design Week: User Journeys for Damn Good Digital DesignPhoenix Design Week: User Journeys for Damn Good Digital Design
Phoenix Design Week: User Journeys for Damn Good Digital Design
 
Tenure track socialmedia_10082010
Tenure track socialmedia_10082010Tenure track socialmedia_10082010
Tenure track socialmedia_10082010
 
Rich UX Research for Everyone
Rich UX Research for EveryoneRich UX Research for Everyone
Rich UX Research for Everyone
 
Content Strategy: Do It For Your Users
Content Strategy: Do It For Your UsersContent Strategy: Do It For Your Users
Content Strategy: Do It For Your Users
 
Build Your Own Contributors, One Part At A Time
Build Your Own Contributors, One Part At A TimeBuild Your Own Contributors, One Part At A Time
Build Your Own Contributors, One Part At A Time
 
How to Create Content for SEO That Earns Me Links?
How to Create Content for SEO That Earns Me Links?How to Create Content for SEO That Earns Me Links?
How to Create Content for SEO That Earns Me Links?
 
Defying the itch to stitch
Defying the itch to stitchDefying the itch to stitch
Defying the itch to stitch
 

Recently uploaded

Introduction to Firebase Workshop Slides
Introduction to Firebase Workshop SlidesIntroduction to Firebase Workshop Slides
Introduction to Firebase Workshop Slidesvaideheekore1
 
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...kalichargn70th171
 
Understanding Plagiarism: Causes, Consequences and Prevention.pptx
Understanding Plagiarism: Causes, Consequences and Prevention.pptxUnderstanding Plagiarism: Causes, Consequences and Prevention.pptx
Understanding Plagiarism: Causes, Consequences and Prevention.pptxSasikiranMarri
 
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfPros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfkalichargn70th171
 
Zer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfZer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfmaor17
 
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...Bert Jan Schrijver
 
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdfAndrey Devyatkin
 
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptx
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptxThe Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptx
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptxRTS corp
 
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full Recording
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full RecordingOpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full Recording
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full RecordingShane Coughlan
 
Advantages of Cargo Cloud Solutions.pptx
Advantages of Cargo Cloud Solutions.pptxAdvantages of Cargo Cloud Solutions.pptx
Advantages of Cargo Cloud Solutions.pptxRTS corp
 
Keeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldKeeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldRoberto Pérez Alcolea
 
Understanding Flamingo - DeepMind's VLM Architecture
Understanding Flamingo - DeepMind's VLM ArchitectureUnderstanding Flamingo - DeepMind's VLM Architecture
Understanding Flamingo - DeepMind's VLM Architecturerahul_net
 
Best Angular 17 Classroom & Online training - Naresh IT
Best Angular 17 Classroom & Online training - Naresh ITBest Angular 17 Classroom & Online training - Naresh IT
Best Angular 17 Classroom & Online training - Naresh ITmanoharjgpsolutions
 
Effectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorEffectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorTier1 app
 
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdfSteve Caron
 
VictoriaMetrics Q1 Meet Up '24 - Community & News Update
VictoriaMetrics Q1 Meet Up '24 - Community & News UpdateVictoriaMetrics Q1 Meet Up '24 - Community & News Update
VictoriaMetrics Q1 Meet Up '24 - Community & News UpdateVictoriaMetrics
 
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...OnePlan Solutions
 
What’s New in VictoriaMetrics: Q1 2024 Updates
What’s New in VictoriaMetrics: Q1 2024 UpdatesWhat’s New in VictoriaMetrics: Q1 2024 Updates
What’s New in VictoriaMetrics: Q1 2024 UpdatesVictoriaMetrics
 
eSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolseSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolsosttopstonverter
 
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jGraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jNeo4j
 

Recently uploaded (20)

Introduction to Firebase Workshop Slides
Introduction to Firebase Workshop SlidesIntroduction to Firebase Workshop Slides
Introduction to Firebase Workshop Slides
 
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...
The Ultimate Guide to Performance Testing in Low-Code, No-Code Environments (...
 
Understanding Plagiarism: Causes, Consequences and Prevention.pptx
Understanding Plagiarism: Causes, Consequences and Prevention.pptxUnderstanding Plagiarism: Causes, Consequences and Prevention.pptx
Understanding Plagiarism: Causes, Consequences and Prevention.pptx
 
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdfPros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
Pros and Cons of Selenium In Automation Testing_ A Comprehensive Assessment.pdf
 
Zer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdfZer0con 2024 final share short version.pdf
Zer0con 2024 final share short version.pdf
 
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
JavaLand 2024 - Going serverless with Quarkus GraalVM native images and AWS L...
 
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf
2024-04-09 - From Complexity to Clarity - AWS Summit AMS.pdf
 
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptx
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptxThe Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptx
The Role of IoT and Sensor Technology in Cargo Cloud Solutions.pptx
 
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full Recording
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full RecordingOpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full Recording
OpenChain AI Study Group - Europe and Asia Recap - 2024-04-11 - Full Recording
 
Advantages of Cargo Cloud Solutions.pptx
Advantages of Cargo Cloud Solutions.pptxAdvantages of Cargo Cloud Solutions.pptx
Advantages of Cargo Cloud Solutions.pptx
 
Keeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository worldKeeping your build tool updated in a multi repository world
Keeping your build tool updated in a multi repository world
 
Understanding Flamingo - DeepMind's VLM Architecture
Understanding Flamingo - DeepMind's VLM ArchitectureUnderstanding Flamingo - DeepMind's VLM Architecture
Understanding Flamingo - DeepMind's VLM Architecture
 
Best Angular 17 Classroom & Online training - Naresh IT
Best Angular 17 Classroom & Online training - Naresh ITBest Angular 17 Classroom & Online training - Naresh IT
Best Angular 17 Classroom & Online training - Naresh IT
 
Effectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryErrorEffectively Troubleshoot 9 Types of OutOfMemoryError
Effectively Troubleshoot 9 Types of OutOfMemoryError
 
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf
[ CNCF Q1 2024 ] Intro to Continuous Profiling and Grafana Pyroscope.pdf
 
VictoriaMetrics Q1 Meet Up '24 - Community & News Update
VictoriaMetrics Q1 Meet Up '24 - Community & News UpdateVictoriaMetrics Q1 Meet Up '24 - Community & News Update
VictoriaMetrics Q1 Meet Up '24 - Community & News Update
 
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
Tech Tuesday Slides - Introduction to Project Management with OnePlan's Work ...
 
What’s New in VictoriaMetrics: Q1 2024 Updates
What’s New in VictoriaMetrics: Q1 2024 UpdatesWhat’s New in VictoriaMetrics: Q1 2024 Updates
What’s New in VictoriaMetrics: Q1 2024 Updates
 
eSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration toolseSoftTools IMAP Backup Software and migration tools
eSoftTools IMAP Backup Software and migration tools
 
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4jGraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
GraphSummit Madrid - Product Vision and Roadmap - Luis Salvador Neo4j
 

Conflicting attitudes towards commenting and documentation

  • 1. A data-driven look at conflicting attitudes towards commenting and documentation. @veronica_hanus #PyGotham
  • 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. Comments get a pretty bad rep! @veronica_hanus
  • 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. Finally! Time to refactor! @veronica_hanus
  • 8. @veronica_hanus Don’t Repeat Yourself! Keep it D.R.Y.! Undocumented code is unusable!
  • 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
  • 16.
  • 17. @veronica_hanus [Subtext] HEY Newbie! Your struggle BORES ME & shows you are a bad programmer! KTHXBYE
  • 18. Design has methods & tools! Let’s face it… comments are magic @veronica_hanus
  • 20. Comments can: - Label - Questions - Notes - Outline - Storage - References - Support overwhelmed learners @veronica_hanus
  • 21. @veronica_hanus # V!: TODO [........] # Veronica was heree! Move fast & break things write bad comments
  • 26. 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
  • 35. @veronica_hanusMake your own! https://www.ascii-art-generator.org/
  • 36. “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
  • 38. 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
  • 39. 👇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 👋me@veronicahanus.com Survey: http://bit.ly/comment-use Video & Slides 🔜 http://veronicahanus.com/talks 🙌Write the comments you wish you had!
  • 40. 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-9ffc7a ef870c - Guidelines for comments: https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html @veronica_hanus
  • 41. 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 - Programmer in bath: https://footage.framepool.com/en/shot/798293950-bath-tub-bathroom-information-technology-student-university - A good programmer: https://code.likeagirl.io/herstory-software-engineer-maker-estefannie-d4fdec7b069a - Squirrels wants you to stop: https://patch.com/florida/brandon/stop-right-there-brandon-squirrel-wins-world-photo-contest - Sad programmer: https://drawception.com/game/H73GxcwzmW/a-sad-programmer-playing-drawception/#panel-1537906 - Inconceivable: https://images.app.goo.gl/2nnv4DN7E8yFkeKj8 @veronica_hanus
  • 42.