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=
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.
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
To comment or not to comment?
“To comment or not to
A data-driven look at conflicting attitudes towards
commenting and documentation.
Critique the comments!
Comments as first documentation
Purpose of comments:
➔ Summary: authorship, purpose
➔ Describe functions
➔ Clearify “tricky code”/unclear decisions
➔ Easier stand-alone doc-writing!
➔ A “notepad”
➔ Tell why!
Confusion about comments
And then we debate
Best practices we can get behind
Code tells how,
comments tell why
Line-by-line show lack
Docstrings should have
Outdated comments ==
Too much is too much
Design has methods
Let’s face it… comments are magic
- Store questions
- Notes to research
- Code outline
- Storage for
Good code is DRY
The way you learn
is an antipattern!
- Code better
- Don’t use comments
- Use only the right
- Only code matters
- 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
- How long programming?
- How long professionally?
- Path to programming?
- 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
The best use of comments
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
➔ Comments == docs? @veronica_hanus #PyTexas2019
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)
- 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-
- Guideline for docs: https://opensource.com/business/15/5/write-better-docs
- Read code? Read docs too! (& resources for doc generation):
- 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-
- Guidelines for comments: https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html
- ASCII comments: https://twitter.com/johnregehr/status/1095018518737637376
- “Suffering on StackOverflow”: https://medium.com/@Aprilw/suffering-on-stack-overflow-
- 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