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=
6. And then we debate
@veronica_hanus #PyTexas2019
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. 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. 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. 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
23. The best use of comments
@veronica_hanus #PyTexas2019
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. 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. 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. 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
Editor's Notes
Slide 1: To comment or not to comment?
Who here has ever made a “comment to themselves” as they were coding within the code itself?
(if few hands)
There could be lots of reasons to do that!
Maybe
there was a variable they were scared to change,
they had just copy-pasted a section of code from online and they wanted a quick note about what it did - because it’s easy to forget what you didn’t write…
they had made choice they wanted to explain to their future selves - because it’s easy to forget *why* you wrote what you wrote
Let’s try that again - anyone use comments within their code?
With all these reasons to add comments, you may wonder why we aren’t all commenting all over the place...
Slide 2:: Good bad ugly…
With all these great ways to use comments, what happens when someone who is learning uses commenting to “hold their place” and releave some of their cognitive load as they change direction, look up terms and code samples, etc.
In our first example, the tutorial that started the project is cited at the top, and many would find this reasonable - the comment might survive in the codebase for some time and be added to documentation as the project grows.
In our second, we see something a little more complicated. Our hero was trying to use Beautiful Soup to scrape the website and send an alert when her favorite on-campus climbing wall was open. But she hadn’t done this before and has notes to herself listing what she will need to do, 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.
Before we dive in, what makes a programmer?
Knowing language / methods
Applying problem solving / creative thinking
Communicating / writing *usable* code
We spend a lot of time on that first point - knowing a language and it’s methods - but I want to talk about the journey through the other two (creative thinking & communicating) since they are an important part of getting to the mastery we all desire.
Documentation is what allows code to be used, expanded, and adapted and for community to formed.
Avoid causing other programmers pain!
As I was approaching comments-as-docs, I
Slide 3:: Confusion about comments
A lot of people feel this (“no comment” is bad code)
But this might also be true (comment labeling a cat a cat)
Maybe you’re worried about the balance (helpful comments but not distracting ones) and maybe like this claims (“mandatory shit we all pass through”) our stress about commenting and documentation is “something we have to pass through” as we learn the proper balance
Slide 3:: Confusion about comments
We hear this (comments rot)
But it’s easy to forget the learners who our comments are helping (not until you learn)
Remember how one of our goals is creating the most usable code we can?
Slide 3:: Best practices we can get behind
This is one of those topics that folks readily disagree on, but...
We can agree:
Docstrings should have inputs, outputs, transformation
Outdated comments == lies
Sometimes we say:
Code tells how, comments tell why
Don’t Waste Everyone’s Time (WET)
Line-by-line may indicate lack of understanding
The difficulty that many of us have is there is a lot of variation is what is considered best practice for comments.
This explaination is clear enough - certainly there’s variation and room for different styles (evidenced by companies having style guide that include what should be included in a docstring or comment) - but we can all agree that comments, if used properly (if we can ever learn what that means!), can be an invaluable part of a codebase.
Slide 4:: But comments are also magic
All of this “best use” talk is important, but I hope we can go back and remember (and for some of us it’s way back) when we were writing our first lines of code and encountered the power of the comment. Maybe we wrote redundant code and our more experienced coding buddy kindly said “hey, let’s leave that there a minute” and wrote the correct code but left the commented out portion long enough for us to compare the two functions. Maybe someone critiqued our variable name but showed us how we could make “a note to ourselves” about the meaning as we learned to write better ones. Comments-for-debugging & comments-as-memory-aids-as-we-learn-better-habits are two common ways they are introduced but the realization that, yes, you can write a note to yourself, to future code users (or anyone!) and the interpreter just ignores it? It seems like magic. You have the power to write secret notes for a future reader in your editor!
Now, people use this power differently, but most of the new programmers I have worked with start throwing comments everywhere - I’ve seen comments for variables, comments that hold questions to ask a mentor later, comments made during pairing to record some new, related bit of knowledge, comments used as an outline for code yet to be written, comments holding code that we don’t use but aren’t quite ready to get rid of yet, even comments that record the URL of the website where our new programmer had found some insight or to give credit to the true author of their stack-overflow copy-paste.
(animation of my list of how comments are used by newcomers)
Maybe you did some, all, or none of these things, but I promise I have seen at least one new programmer do everything single one. With more experience, we know that not all of these make sense, and we wouldn’t want to see them smeared across our codebase - but to someone new, they each service a purpose.
Let’s stop and look at that last two:
Why would our gender-neutral hero or heroine add a reference to where they found a code snippet or where they had learned whatever they implemented? They can just find it again! We aren’t going to lose the ability to search the internet anytime soon!
But do they know they can? When you have to look up how to start a function or run your code each time you do it, when you are still learning the right terms to search (eg. HTTP’s get and post), when you are worried about asking for help too much just in case your support system tires of you, when all or any of these things are happening and you are stuffing so much into your brain and you are scared and entirely unconfident (but maybe faking it), it’s really hard to feel confident that you will ever find anything again. Suddenly that URL tucked between lines of code that you know might not be able to write again by yourself makes a lot of sense.
And why would someone save code that no longer serves them. Anyone who has walked up to or (in my case, swam into) their closets and attempted to Marie Kondo their clothing or other possessions can tell you exactly why! What if I need it again? It *used* to spark joy. I’ll never find another one. When you are very new, deleting even duplicated, unhelpful code could bring up a little “what if I need it back?” panic.
(animation of tweet “I don’t know what I did today”)
As I progressed and passed through this stage, I was active in several programming communities, but I started seeing the a trend…
Slide 5:: Good code is DRY
I had seen the StackOverflow DRY smackdown. It’s about what you would expect: Someone new comes in and exposes their vulnerability only to hear they are WRONG WRONG ALL THE WAY JUST WRONG. As the time I dismissed this as “a few jerks on the internet” and promised myself I would cultivate my in-person and online support networks so I wouldn’t have to feel the insecurity the question’s author must be feeling. It was, after all, a space where one-upmanship was part of the culture.
But I started seeing the same in other online spaces: some competitive, some learning-oriented, but all beginner focused. Once I started seeing this attitude, I noticed it everywhere. Why were we doing this?
In most close-knit communities and during in-person pairing, I noticed it was often an intermediate beginner - someone who had been learning to program months or a year more than there mentee - who were dishing out the DRY ultimatums. Was this is a “toxic beginner who knows a bit more” effect?
I wanted to show you an example of my earliest comments - but none of them exist.
You see, before I was starting a project and immediately committing changes to version control, I was advised that if I wanted to be taken seriously as a developer, I would have to only commit my “cleaned up” (that means only best-practice comments!) code. So my last step before committing every early project was to (painfully) erase each of the notes that had helped me get so far into the project. Then save, add, commit, push. This caring friend, who was my main advisor at the time, had taught me that the commenting scheme that I had created to support myself wasn’t ok.
I’m not alone: New learners quickly become interested in “best practices”. They want to write the best code they can, as quickly as they can. Without the experience to know the “why” for our “rules,” they can fall into the great toxic pitfalls of newbie programming: “just tell me how to do it” & decision paralysis.
Remember the learning-overwhelm we talked about earlier? In my experiences, questions about commenting are often asked in a way that invites a binary answer: “how many comments are too much?” suggests that there might be a set “too much”. 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.
The worst part is the effect these shut-downs have on others. Newcomers’ superpower is their creativity and passion. If treat them not as learners but put the expectations we would have of a professional with years of experience, we’re squelching their ability to explore.
The next time I saw someone being told their commenting style was “an anti-pattern”, I couldn’t let it go.
Slide 6:: The questions
I started asking everyone I could about their commenting habits.
A lot of people claim their code has always been DRY. I was left to conclude that either all my friends were coding robots who had always followed best practices or their perception of themselves had changed over time.
(animation of twitter poll)
My first poll indicated that a lot of folks were always DRY, but that wasn’t what I was seeing with learners in person.
I wanted to look closer at these conflicting responses. I needed to ask some questions and do so in a way where the person I was speaking to didn’t have to save face - remember, I had already seen how easy it is to absorb those toxic “don’t show your vulnerability” habits. Plus, I’m still a scientist at heart and the answer is always in the data.
I decided to ask some deeper questions: (and I am about to put too many words on a slide, ARE YOU READY?)
Current/recent use: Comment uncertainty, Function-level comments, Clarification, Unused code, Other
Changes over time?
When comments added: Scoping & planning, As functions written, Pairing, As I learn people don’t understand, Clean-up
Changes over time?
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
How long programming?
How long professionally?
Path to programming?
Now, I’m about to share some results with you.
Maybe you want to…
ASCII to explain what your code does
Create whole man pages describing sections of your code
Maybe right now those “obvious” comments aren’t so obvious to you - as you learn naming conventions this will change but for now postits on all the cats
The best use is the use that helps you - the rest is going to come but for now learn to solve the problems you have. The problem solving you do now will be with you throughout your careers - certainly longer than this year’s flavor of javascript!
In the spirit of this quote - the best comments are a huge help but the “perfect” comments don’t come without trial and error.
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
Why do beginners need to go (“grow”) through this? (We’ll use me as an example)
The path
All this is colored by my programming journey
Line-by-line tutorials (eg. Codecademy),
Broadly outlined projects (eg. Boston Python Women’s Workshop),
Lots of learning motivated by but unconnected to projects (eg. best practices: variable names, modular code, doc strings… it’s a process),
Individual (unguided) projects (eg. HTML/CSS website), Contributing to other’s work
Different styles for different stages:
Comments to plan
For me, this was transition between tutorials & personal projects
“Comment-driven development”
Line-by-line comments
In “Codecademy phase”, I commented every line I wrote to make sure I understood what I was writing. Later, I even added links to any Stackoverflow or docs I had found helpful b/c struggled to find the right keywords / google effectively. I wanted to be able to review my resources and I wanted people seeing my code to understand how much was “mine” (Sometimes learners have to be “selfish” and comment for themselves!)
Function-level comments (Docstrings)
Getting into an area that few people will argue with
In-line clarification (variables, etc.)
So now, we’ve dived into our survey responses (so far!) & heard how and why one person adapted different commenting styles throughout the start of their career. Maybe, like many of the people I spoke to, you haven’t thought about how the conflicting urges of “wanting to be the best programmer you can be as quickly as possible” and “doing and owning what works for own learning” play out in a new programmer’s head. Maybe you’re really bummed or remembering a time when you inadvertently
