I'm gonna show you two pieces of code.

They do the same thing.

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.

Okay, so look at it.

Read it.

I'll give you a minute.

Okay.

Which piece of code is more clean?

A.

Raise your hand for a raise.

Your hand for B.

Okay, great.

All right.

Who?

Which one is clean?

All right, read it.

Which ones, eh?

Okay, Now, how about B?

All right, great.

We're about 50.

50 for each one.

What?

What is What does this block of code do?

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

All right?

We got a user agent.

All right, cool.

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

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

Yeah, almost everybody.

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

Uh, clean code by Robert C.

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.

I both agree and disagree with this.

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'm Sarah Drasner.

I'm ah view korma member of you.

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.

You all today, especially in Hawaii.

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

That was awesome.

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.

Where things air steps in a recipe.

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.

Sophie Albert posted this.

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.

Why?

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

And so it wasn't very straightforward.

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?

That wasn't super eligible.

What about this?

Does anybody know what this does, right?

This Does anybody know what this does?

Probably not.

This targets Firefox versions to the three.

This targets chrome, sapari and opera.

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.

Maybe they solve that browser issue.

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

Who's smart?

We are who writes clean code.

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

Look at how clean clear your coat is.

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.

But that even changes over time.

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.

But on a team where the skill sets are more of a Venn diagram, you might not have the same opinions.

Might not have the same backroom, and that's okay.

It might look like I'm advocating for the smaller skill set circle, but look at how much more ground this covers.

You have a larger spread of expertise when you have a team that looks like this or say you get junior developers on your project on bigger teams, where you have a lot of junior developers and engineers from all types of backgrounds, people might not outright tell you that they need you to comment, but a lot of times they'll express gratitude.

When you do, comments could be like chapters of a book.

If you think of a book, it's the same amount of information, whether you have paragraphs or chapters or indexes.

But we split those up.

Why, so that you can skim easier so that you can pick things back up if you've been gone from time away.

And that's true of our code.

Two Commenting or sexual sections of code allows people to get to the peace that's most relevant to them.

But you might say we have imports and modules and functional programming.

Absolutely.

That is awesome.

And I'm so excited about that.

But necessarily there's gonna be a time when you get to a larger piece of code that just has to exist.

Sometimes commenting different sections or making some separation can help people find their way more quickly, a guide to keep the logic straight while writing the code.

Sometimes I do this thing where if I have, ah, you know, a big project where I'm managing Aton of state from a bunch of different things.

All right, something like this out get the request for the server.

Give us an error if it failed.

Do X thing with the request form at the date is that, like so and so on and so forth, just making a long to do list of little section so that I could break down my tasks.

Now these air weird one because these aren't the kind of comments you want to keep around.

If you keep them around, they could be misleading, and we'll get to that in a minute.

But they're really helpful while you're writing the code so you can break your tasks down into smaller bits.

So in the process of writing all of this code, it could be really helpful to write it like this.

But then you should probably remove it, because when left in your code, as is, these comments can be a little screwy to read later.

My perfect world suggestion would be to use these comments at the time of writing and then revisit them.

After, as you delete them, you can ask yourself, Does this do this in the most elegant way that I could?

Is there not another comment that I could write that might explain why this is necessary.

What would I think is most useful to express to another from another Mother, This is okay.

You're a factor now.

This is an interesting one.

This isn't This isn't my best work.

But we had to get it in by the deadline.

How many of you had have had a really aggressive product deadline?

Most of you.

Okay, maybe you implemented a feature that you yourself disagreed with.

And you're like, I don't know about this.

And they were like, Oh, don't worry, it's an A B test.

Or don't worry, don't worry.

It's just temporary.

And then it lived on forever.

Ever Que hora music.

As embarrassing as it is to write a comment like this, sometimes it's super helpful as a maintainer.

If I come across a comment like this, I'm not thinking like, what's wrong with this person?

How can I sabotage their morning commute?

I e I I'm thinking OK, I know that they were probably under a lot of pressure and it's okay for me to re factor.

I don't even spend that much time thinking through their process.

I'm all about like All right, let's get in the mode where I can improve on this so that could be really helpful for a maintainer.

I will say Don't use this as a crutch, though.

You can just put this on every block of code and call it a day right.

But it can be helpful to let other people know what's going on commenting as a teaching tool.

Are you a node shop that's been given a client?

That's all, Ruby.

Maybe it's totally standard Ruby, but everyone's in a little over their head.

Are you writing a tutorial for someone?

These air limited examples when writing out the how can actually be helpful.

The person is literally learning on the spot and might not be able to Justin for something because they've never seen that code before in their lives.

Comment that shit learning is humbling enough as it is without them having to ask aloud what you could.

They could more easily in fur on their own.

Commenting doesn't just have to be a teaching tool, either.

This, uh, this person did a really cool thing where they held them themselves accountable for a tutorial by commenting above every line of code exactly what it was doing?

That's awesome.

He's holding himself accountable for learning that material line by line.

So it could be a way for you to also, you know, keep yourself accountable for what you're learning and teaching as well.

I stack overflowed the bejesus out of this.

Did you just copy a whole block of code from stack overflow?

That's OK.

We've all been there.

Something that I've done that saved me in the past is to put a link from where I got it, where I found it.

And sometimes people say to me, But then I don't get credit for writing that code, and I would tell them You're optimizing for the wrong thing.

Inevitably, people have different coding styles, and this is important because what if you level up later?

What if you're smarter later on and you revisit this block of code and it's in a completely different style than you're used to?

And you actually no more.

You might spend a lot of time sitting there going, Why did I write it like this when I know X is true?

Another thing is, stack overflow is I got a lot of traffic.

You might go to that post later and find out there's a better response that happens all the time.

So this is a really good way of for you to keep track of those things.

As he moved forward.

Comments could be really helpful.

April Wenzel wrote.

This really awesome post called It's Time to Retire are TFM, and this is why I think it's useful toe add these comments.

Sometimes she makes a really good point in this that in tech we get comfortable with a sort of survivorship bias.

And what I mean by that is, well, I had to go through it, so you have to go through it, too.

But the job of a senior engineer the job of a more advanced engineer is to make sure that the other team can scale efficiently.

The job of a senior engineer is to make sure that everyone else can get going and be as productive as humanly possible.

And sometimes comments can help with that.

And that means helping, not letting, leaving people on their own.

If you know the path.

All right, let's say going into the bad writing comments gets a bad rap sometimes, and that's because bad comments exist So let's talk about some ways that we can avoid doing this while writing them.