1 of 38

“To #comment or not?”

A data-driven look at conflicting attitudes towards commenting and documentation!

@veronica_hanus

#RemotePythonPizza

2 of 38

Documentation can

cause or relieve

programmer pain!

@veronica_hanus

3 of 38

are documentation?

What if

#COMMENTS

DUN DUN DUN…!

@veronica_hanus

4 of 38

#COMMENTS get all the time.

SMACK-TALKED

Good C0DE

speaks for itself!!!! >:O

Comments rot :(

Keep it D.R.Y.!

Comments mean time to refactor

¯\_(ツ)_/¯

?

!

?

!

@veronica_hanus

5 of 38

When does #REFACTORING happen?

Too often...

New Work > Refactoring
Time for Feedback? No.
Feels like a “Nice to Have”

✓

Refactor when….

Can’t Stand it Anymore
Problem Grows
Refactoring == Self-Care

Finally, time to refactor!

@veronica_hanus

6 of 38

Outdated comments

can mislead.

Well-placed comments can protect critical code from errors.

@veronica_hanus

7 of 38

@veronica_hanus

8 of 38

@veronica_hanus

In our second, we see something a little more complicated.

When I worked at MIT, my lab was a few hundred feet from a student-run climbing wall which I wanted to be able to visit whenever it was open. Problem was, it was only open when a student decided she wanted to open the wall. To catch the wall when it was open, I would have to hit refresh on my browser again and again.

I used Beautiful Soup first the first time to scrape the website and send an alert when it opened.

(CLICK)

Since it was my first time:

notes to herself listing TODOs,
code that she has commented out, and
more notes expressing her confusion - including my favorite comment to date “Oh, it’s a list. Thank god.”

Would you want to contribute to a codebase that had similar pile-ups of comments throughout?

I feel confused looking at this now, and I wrote it.

9 of 38

v

10 of 38

We Can Usually Get Behind

Code is the “how”,

Comments are the “why”

Don’t Waste Everyone’s Time

(WET)

Line-by-line shows a

Lack of Understanding

Docstrings should have

Inputs, Outputs, Transformation

Outdated Comments == Lies

Too Much is Too Much!

#BESTPRACTICES

@veronica_hanus

11 of 38

And the best (WORST)

advice goes to...

Just

@veronica_hanus

Code

Better

(Thanks a lot, Internet)

12 of 38

Typical Newbie Question on StackOverflow

@veronica_hanus

THOUGHTFULLY

ASKED QUESTION ON THE INTERWEBS

Translation: N00B, ur sTrUgGle bOrEs mE & u R a BAD pRoGrAMeR 😘

@veronica_hanus

13 of 38

Comments can:

Label
Questions
Notes
Outline
Storage
References
Support overwhelmed learners

Comments can:

Label
Questions
Notes
Outline
Storage
References
Support overwhelmed learners

@veronica_hanus

14 of 38

# V!: TODO� [........]

# Veronica was heree!

Move fast & break things write bad comments

1 # VeRoNiCa wuz here

2 #

3 # move fast & break

4 # things

5 #

6 # (I mean move fast &

7 # write bad comments)

8 #

@veronica_hanus

I was talking to a dev who as they put it “wants to get things working asap”. When they fork a project and begin to modify and bring if bits of their own, they leave whatever existing comments in the code but add their own *with their name attached* to seperate them. Sure, there’s version control, but that’s an extra step.

Their first drafts are covered with comments that start “hey Veronica” or keep their place with a “Veronica was here”.

Now, I know we don’t want to see that in our code, but this person is making art, often by combining and altering and cobbling together and they want to move fast and be able to both test their ideas and complete their projects… if you think about it, those are pretty universal goals.�

Many of us love “move fast and break things” so who wants to take away the right to “Move fast and write bad comments” from someone who is experimenting? They might even be able to avoid breaking some things!

Feeling even more confused about how other devs use comments than you were when you started this talk? Me too. I think it’s time for a survey!

15 of 38

@veronica_hanus

16 of 38

A survey, now backed by non-trivial DATA!

AGREE/DISAGREE (1-5):

Comments:

Help me remember what my code does ✦ Clarify my thinking ✦ �Help me learn ✦ Save time ✦ Are deleted before projects is shared

Yes to function-level, no in-line ✦ Clear code is self-documenting

RADIAL CHOICES (Choose 1)

Current/Recent Use: Comment Uncertainty ✦ Function-Level Comments

Clarification ✦ Unused Code ✦ Other

When Comments Are Added: Scoping & Planning ✦ As Functions Written ✦ Pairing

As I Learn People Don’t Understand ✦ Clean-up

@veronica_hanus

17 of 38

@veronica_hanus

18 of 38

@veronica_hanus

19 of 38

@veronica_hanus

20 of 38

@veronica_hanus

21 of 38

“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

22 of 38

Comments

teach us

about ourselves

@veronica_hanus

23 of 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

What can we do?

The goal: Support learners where they are at, praising their accomplishments, while pointing them gently toward the future
If you can remember our overwhelmed learner, it’s a lot easier to do this!
Empathy in our corrections, praise for inguity / all forms of problem-solving while showing the future
Those who hadn’t struggled suggested a dive :: “Clean Code” came up several times
Tools (should we “turn off” comments instead of pushing for styling?)
What can we say?

Examples:

Not “good code doesn’t need comments”
“I see how you solved [their problem] with your comments - at some point you’ll want to move toward [alternative] but I see how this is useful to you now”

The words don’t matter as much as the acceptance of both their current state and the future they should be aware of/looking for
Remember

24 of 38

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!

👇Is your company recruiting a

DevRel or Dev Advocate?👇

🙌@veronica_hanus🙌

A big thank you to

each of you for coming,

the Python Pizza organizing team for the opportunity and

the ~170 internet-folks who have shared their “comments on comments”

25 of 38

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

26 of 38

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

27 of 38

Make your own! https://www.ascii-art-generator.org/

@veronica_hanus

28 of 38

While most experienced programmers are happy to discuss the nuance of “when to comment”, a number of inexperienced programmers have heard “good code is dry” and being exposed to this binary can cause a lot of anxiety.

I only came to recognize toxic beginner culture after I had begun to participate in it. Sure, I set aside time to patiently help with set-up, readily offered to be the “big” at meetup pairing sessions, and answered forum questions - but none of these actions were really selfless. As much as those interactions helped the folks I worked with, I was also seeking affirmation. Each “you’re wrong” I dished out, presented kindly or tersely, reminded me that, yes, I do know things others don’t. That, as much as I struggled as a self-taught programmer, someone was “behind me”.

Right? That’s... not good.

29 of 38

!@#$

$#!@

DON’T

REPEAT

YOURSELF!

KEEP IT D.R.Y.!

CODE

WITHOUT

DOCUMENTATION

IS UNUSABLE!

@veronica_hanus

30 of 38

Not certain

Each function

In-line

Unused code

@veronica_hanus

31 of 38

@veronica_hanus

32 of 38

@veronica_hanus

33 of 38

34 of 38

@veronica_hanus

35 of 38

Not certain

Each function

In-line

Unused code

@veronica_hanus

36 of 38

@veronica_hanus

37 of 38

@veronica_hanus

38 of 38

@veronica_hanus