Name: The Art of Code Comments - Sarah Drasner | JSConf Hawaii 2020
Uploaded: 2020-03-28T17:40:36.000Z
Duration: 21 min 13 s
Description: Thousands of YouTube videos with English-Chinese subtitles! Now you can learn to understand native speakers, expand your vocabulary, and improve your pronunciation...

Present continuous

All right, So to kick it off here, we're gonna do a vote.

Future simple

Um, and you're gonna decide which piece of code does it expresses it in the most clean way.

Which piece of quote is the most clean will do it by a raise of hands.

You can go ahead and just yell it out at me.

How many of you read by a show of hands have heard this phrase?

You don't need comments if you write clean code.

So this is where I think a lot of misconceptions lie in the book.

Martin he talks about how Commons shouldn't be necessary because code should be self documenting that if you feel ah comment is necessary, you should rewrite it to be more legible.

In the process of writing a comment, you can often find things that could be written better, but it's not an either or.

I might still be able to rewrite that comment to be more self documenting and also write a comment as well for the following reason.

Coat can describe how, but it cannot explain why now.

This isn't a new premise at all, but it's a common theme that I see and helpful comments that I've come across the ability to communicate something that code can't or can't precisely.

And all of that said, there's not just one way or right are correct way to write a comment.

I believe that our collective discourse about code comments is far too shallow.

There are good comments and their bad comments they could make.

Our code base is more legible and they can mislead us.

They can guide us and they could be a crutch.

So for that reason today, we're gonna be talking about the art of code comments.

I also, um, head of developer experience at Nelle.

If I which is neither Netflix or Shopify, as confusing as it is for my parents, it is a really awesome way to deploy sites and APs that I love.

That's why I asked them if I could work there.

So I'm really pleased to be Toby with you.

I'm sure we always appreciated the Gap Day yesterday.

So I mentioned there's some nuance to this.

There's good comments and there's bad comments, so we're gonna go over both of them.

We're gonna start with the good comments first.

What is the why Many examples of good comments can be housed under this category code explains what you'd like the computer to take action on, and you'll hear people talk about declaring a code where they're saying rather than, you know, imperative code.

You're basically telling the computer what you wanted to do in the computer does the heavy lifting.

Well, our comments can also be more complete clarity ve we had to write this function because the browser interprets everything is a box.

This code doesn't describe what the code below it will do.

It doesn't describe the actions that will take.

If you found a more elegant way of writing this, you'd feel confident that you could do you could re factor it.

And because of this, less maintenance is required in order to keep these comments around.

So if you found a better way to write this, you probably wouldn't have to rewrite this comment.

I think the funniest version of this is from the former manager of reactor core.

This comment is longer than the Read me to some of my repose.

The only piece of code is that tiny little bit at the bottom there.

But this, you know, all of that explanation was really necessary.

Because it was a particularly nasty coat, a bit of code that and bug, that she spent a really long time to bugging.

And just that one line of code doesn't express all of the things that that one piece of code does can also clarify what's not let, typically legible by humans.

Remember the user agent thing that we saw before?

This targets Firefox versions to the three.

I've written code that needs something like this, and in order to avoid another maintainer or future me assuming I took some mushrooms on the way to work, it's great to tell people what the heck let's for, especially in preparation for a time when you no longer need it.

Or maybe you're not supporting that browser anymore, and you can remove it.

We d'oh it, but you don't have to look at you don't have to comment.

But think back to that first exercise we did.

We weren't all on the same page about what was clean.

The room was divided at 50 50 on what was clean and what wasn't.

People don't always agree on these things, and it's convenient, really subjective, and you can always assume that what you're doing is the most clean way of representing it.

The code that I think is clean was clean five years ago is not what I think is clean today, and you level up in different ways.

Another thing is that we're all knowledgeable in different ways.

If you're on a team where everybody's skill set is more tightly, tightly knit, you might have more overlaps for what you think is clean.

You might be more on the same page, so maybe this isn't as much of an issue.

Subtitles ListPlay Video

The Art of Code Comments - Sarah Drasner | JSConf Hawaii 2020

process

awesome

tend

conversation