SlideShare a Scribd company logo
A data-driven look at
conflicting attitudes towards
commenting and documentation.
@veronica_hanus #PyDataNYC
@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
PyData 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 PyDataNYC 2019 "To comment or not?"

Collaboration Techniques that really work
Collaboration Techniques that really workCollaboration Techniques that really work
Collaboration Techniques that really work
leisa reichelt
 
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
 
Technical Writing meets Instructional Design
Technical Writing meets Instructional DesignTechnical Writing meets Instructional Design
Technical Writing meets Instructional Design
Sharon Hamilton Jendrisak
 
Tenure track socialmedia_10082010
Tenure track socialmedia_10082010Tenure track socialmedia_10082010
Tenure track socialmedia_10082010
Ines Mergel
 
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
Andrea Sarther
 
Career Hacks for Developers
Career Hacks for DevelopersCareer Hacks for Developers
Career Hacks for Developers
BarElin
 
Based Argumentative paper.docx
Based Argumentative paper.docxBased Argumentative paper.docx
Based Argumentative paper.docx
write12
 
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
dreamwidth
 
Getting to Senior in UX
Getting to Senior in UXGetting to Senior in UX
Getting to Senior in UX
Cyd 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 Center
Chris Avore
 
Publishing 102 11 18
Publishing 102  11 18Publishing 102  11 18
Publishing 102 11 18
Karen Brooks
 
This i Believe CATE2014 presentation
This i Believe CATE2014 presentationThis i Believe CATE2014 presentation
This i Believe CATE2014 presentation
Janet Ilko
 
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
Rebekah Baggs
 
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
 
How to Work Out Loud at your Next Conference
How to Work Out Loud at your Next ConferenceHow to Work Out Loud at your Next Conference
How to Work Out Loud at your Next Conference
Helen Blunden
 
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
Thomas Winters
 
User Experience Pain Free
User Experience Pain FreeUser Experience Pain Free
User Experience Pain Free
Ross Lawley
 
Uxp Pain Free
Uxp Pain FreeUxp Pain Free
Uxp Pain Free
oscon2007
 
Building Business Value From Community Participation
Building Business Value From Community ParticipationBuilding Business Value From Community Participation
Building Business Value From Community Participation
Ben Rubenstein
 
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
 

Similar to PyDataNYC 2019 "To comment or not?" (20)

Collaboration Techniques that really work
Collaboration Techniques that really workCollaboration Techniques that really work
Collaboration Techniques that really work
 
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...
 
Technical Writing meets Instructional Design
Technical Writing meets Instructional DesignTechnical Writing meets Instructional Design
Technical Writing meets Instructional Design
 
Tenure track socialmedia_10082010
Tenure track socialmedia_10082010Tenure track socialmedia_10082010
Tenure track socialmedia_10082010
 
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
 
Career Hacks for Developers
Career Hacks for DevelopersCareer Hacks for Developers
Career Hacks for Developers
 
Based Argumentative paper.docx
Based Argumentative paper.docxBased Argumentative paper.docx
Based Argumentative paper.docx
 
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
 
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
 
This i Believe CATE2014 presentation
This i Believe CATE2014 presentationThis i Believe CATE2014 presentation
This i Believe CATE2014 presentation
 
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
 
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?
 
How to Work Out Loud at your Next Conference
How to Work Out Loud at your Next ConferenceHow to Work Out Loud at your Next Conference
How to Work Out Loud at your Next Conference
 
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
 
User Experience Pain Free
User Experience Pain FreeUser Experience Pain Free
User Experience Pain Free
 
Uxp Pain Free
Uxp Pain FreeUxp Pain Free
Uxp Pain Free
 
Building Business Value From Community Participation
Building Business Value From Community ParticipationBuilding Business Value From Community Participation
Building Business Value From Community Participation
 
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)
 

Recently uploaded

Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
safelyiotech
 
Cost-Effective Strategies For iOS App Development
Cost-Effective Strategies For iOS App DevelopmentCost-Effective Strategies For iOS App Development
Cost-Effective Strategies For iOS App Development
Softradix Technologies
 
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptxOperational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
sandeepmenon62
 
Software Test Automation - A Comprehensive Guide on Automated Testing.pdf
Software Test Automation - A Comprehensive Guide on Automated Testing.pdfSoftware Test Automation - A Comprehensive Guide on Automated Testing.pdf
Software Test Automation - A Comprehensive Guide on Automated Testing.pdf
kalichargn70th171
 
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
gapen1
 
Stork Product Overview: An AI-Powered Autonomous Delivery Fleet
Stork Product Overview: An AI-Powered Autonomous Delivery FleetStork Product Overview: An AI-Powered Autonomous Delivery Fleet
Stork Product Overview: An AI-Powered Autonomous Delivery Fleet
Vince Scalabrino
 
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSISDECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
Tier1 app
 
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
kgyxske
 
Penify - Let AI do the Documentation, you write the Code.
Penify - Let AI do the Documentation, you write the Code.Penify - Let AI do the Documentation, you write the Code.
Penify - Let AI do the Documentation, you write the Code.
KrishnaveniMohan1
 
Alluxio Webinar | 10x Faster Trino Queries on Your Data Platform
Alluxio Webinar | 10x Faster Trino Queries on Your Data PlatformAlluxio Webinar | 10x Faster Trino Queries on Your Data Platform
Alluxio Webinar | 10x Faster Trino Queries on Your Data Platform
Alluxio, Inc.
 
Enhanced Screen Flows UI/UX using SLDS with Tom Kitt
Enhanced Screen Flows UI/UX using SLDS with Tom KittEnhanced Screen Flows UI/UX using SLDS with Tom Kitt
Enhanced Screen Flows UI/UX using SLDS with Tom Kitt
Peter Caitens
 
Building API data products on top of your real-time data infrastructure
Building API data products on top of your real-time data infrastructureBuilding API data products on top of your real-time data infrastructure
Building API data products on top of your real-time data infrastructure
confluent
 
How GenAI Can Improve Supplier Performance Management.pdf
How GenAI Can Improve Supplier Performance Management.pdfHow GenAI Can Improve Supplier Performance Management.pdf
How GenAI Can Improve Supplier Performance Management.pdf
Zycus
 
一比一原版(USF毕业证)旧金山大学毕业证如何办理
一比一原版(USF毕业证)旧金山大学毕业证如何办理一比一原版(USF毕业证)旧金山大学毕业证如何办理
一比一原版(USF毕业证)旧金山大学毕业证如何办理
dakas1
 
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
widenerjobeyrl638
 
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
The Third Creative Media
 
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
dakas1
 
Going AOT: Everything you need to know about GraalVM for Java applications
Going AOT: Everything you need to know about GraalVM for Java applicationsGoing AOT: Everything you need to know about GraalVM for Java applications
Going AOT: Everything you need to know about GraalVM for Java applications
Alina Yurenko
 
Boost Your Savings with These Money Management Apps
Boost Your Savings with These Money Management AppsBoost Your Savings with These Money Management Apps
Boost Your Savings with These Money Management Apps
Jhone kinadey
 
Ensuring Efficiency and Speed with Practical Solutions for Clinical Operations
Ensuring Efficiency and Speed with Practical Solutions for Clinical OperationsEnsuring Efficiency and Speed with Practical Solutions for Clinical Operations
Ensuring Efficiency and Speed with Practical Solutions for Clinical Operations
OnePlan Solutions
 

Recently uploaded (20)

Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
Safelyio Toolbox Talk Softwate & App (How To Digitize Safety Meetings)
 
Cost-Effective Strategies For iOS App Development
Cost-Effective Strategies For iOS App DevelopmentCost-Effective Strategies For iOS App Development
Cost-Effective Strategies For iOS App Development
 
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptxOperational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
Operational ease MuleSoft and Salesforce Service Cloud Solution v1.0.pptx
 
Software Test Automation - A Comprehensive Guide on Automated Testing.pdf
Software Test Automation - A Comprehensive Guide on Automated Testing.pdfSoftware Test Automation - A Comprehensive Guide on Automated Testing.pdf
Software Test Automation - A Comprehensive Guide on Automated Testing.pdf
 
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
如何办理(hull学位证书)英国赫尔大学毕业证硕士文凭原版一模一样
 
Stork Product Overview: An AI-Powered Autonomous Delivery Fleet
Stork Product Overview: An AI-Powered Autonomous Delivery FleetStork Product Overview: An AI-Powered Autonomous Delivery Fleet
Stork Product Overview: An AI-Powered Autonomous Delivery Fleet
 
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSISDECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
DECODING JAVA THREAD DUMPS: MASTER THE ART OF ANALYSIS
 
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
一比一原版(sdsu毕业证书)圣地亚哥州立大学毕业证如何办理
 
Penify - Let AI do the Documentation, you write the Code.
Penify - Let AI do the Documentation, you write the Code.Penify - Let AI do the Documentation, you write the Code.
Penify - Let AI do the Documentation, you write the Code.
 
Alluxio Webinar | 10x Faster Trino Queries on Your Data Platform
Alluxio Webinar | 10x Faster Trino Queries on Your Data PlatformAlluxio Webinar | 10x Faster Trino Queries on Your Data Platform
Alluxio Webinar | 10x Faster Trino Queries on Your Data Platform
 
Enhanced Screen Flows UI/UX using SLDS with Tom Kitt
Enhanced Screen Flows UI/UX using SLDS with Tom KittEnhanced Screen Flows UI/UX using SLDS with Tom Kitt
Enhanced Screen Flows UI/UX using SLDS with Tom Kitt
 
Building API data products on top of your real-time data infrastructure
Building API data products on top of your real-time data infrastructureBuilding API data products on top of your real-time data infrastructure
Building API data products on top of your real-time data infrastructure
 
How GenAI Can Improve Supplier Performance Management.pdf
How GenAI Can Improve Supplier Performance Management.pdfHow GenAI Can Improve Supplier Performance Management.pdf
How GenAI Can Improve Supplier Performance Management.pdf
 
一比一原版(USF毕业证)旧金山大学毕业证如何办理
一比一原版(USF毕业证)旧金山大学毕业证如何办理一比一原版(USF毕业证)旧金山大学毕业证如何办理
一比一原版(USF毕业证)旧金山大学毕业证如何办理
 
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
美洲杯赔率投注网【​网址​🎉3977·EE​🎉】
 
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
Unlock the Secrets to Effortless Video Creation with Invideo: Your Ultimate G...
 
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
一比一原版(UMN毕业证)明尼苏达大学毕业证如何办理
 
Going AOT: Everything you need to know about GraalVM for Java applications
Going AOT: Everything you need to know about GraalVM for Java applicationsGoing AOT: Everything you need to know about GraalVM for Java applications
Going AOT: Everything you need to know about GraalVM for Java applications
 
Boost Your Savings with These Money Management Apps
Boost Your Savings with These Money Management AppsBoost Your Savings with These Money Management Apps
Boost Your Savings with These Money Management Apps
 
Ensuring Efficiency and Speed with Practical Solutions for Clinical Operations
Ensuring Efficiency and Speed with Practical Solutions for Clinical OperationsEnsuring Efficiency and Speed with Practical Solutions for Clinical Operations
Ensuring Efficiency and Speed with Practical Solutions for Clinical Operations
 

PyDataNYC 2019 "To comment or not?"

  • 1. A data-driven look at conflicting attitudes towards commenting and documentation. @veronica_hanus #PyDataNYC
  • 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 PyData 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.