Placeholder Image

Subtitles section Play video

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

  • 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.

  • They just say what it's already doing.

  • I think a lot of people get frustrated because they see comments like this.

  • Stuff like this is a big pain.

  • Why?

  • Because you're reading the same thing twice in two different formats.

  • That gives you no more information, and in fact, it makes you process things twice.

  • It's mental overhead rather than helpful.

  • I've written comments like this, but for whatever the reason, you have to take a step back and be honest with yourself and acknowledge that this comment isn't helpful.

  • From a reader's perspective, it wasn't well maintained.

  • Bad documentation can be worse than no documentation.

  • There's no nothing more frustrating than coming across ah, block of code, where a comment says something other than what the code beneath it does.

  • And I think that that really frustrates people and they tend to get in.

  • The comments are bad area, but the comment is in your coat.

  • It's your job to work on it, even if it means deleting it.

  • So I think sometimes people see comments and they're like, Well, that's optional.

  • That's not you know, I'm working on the code.

  • I don't really have toe, you know, mess around with the comments here, but the comment is literally part of your code, and you're also trying not to, you know, mess up the people who come after you.

  • So even if you disagree with code comments and you see a code comment, just get rid of it if you don't want to maintain it, otherwise you should be maintaining that along with the code.

  • If you don't, it's worse than time wasting.

  • It's misleading.

  • It can lead people down the wrong path if you write your codes to be good quality.

  • To begin with that express the why and not the how you might find that the maintenance issue actually goes away.

  • So if we say we need to use the flip technique to be more performing in every browser, if you switch it the code from using get bounding client wrecked to get B box, which do similar but different things because you didn't write out the how you're not gonna have to read, rewrite everything.

  • You're actually using the same thing because that comment is expressing the why.

  • So then you don't have to re factor the code comments as well.

  • If you write really clean code comments, orders, but for code you changed something.

  • You change something.

  • You know, you like the new code, but you just can't quite get rid of that old code yet.

  • This'll one's tricky because if you're not sure if you're done yet, it's okay to keep these in because maybe you do need to keep it in and use it again later.

  • But hopefully, hopefully you're all working with version control and you're all writing good commit messages.

  • So those comments, those pieces of code that you're commenting should be retrievable for you.

  • You should be able to look back at the thing that you re factored and be able to see what you re factored and retrieve them.

  • If you don't and you move away from the project in the future, the future, you or your future teammates will spend a few minutes trying to figure out what went on here.

  • Do we need this?

  • Will we need this?

  • It's time wasting to do this to people.

  • Trust your instincts and your version control system.

  • Get rid of it.

  • You could have used a better name.

  • I've done this before.

  • I've definitely seen a lot of other people write code like this before where the variable or functions names are one letter and then you comment what?

  • The thing is earlier in the file.

  • This is a waste.

  • I know we all hate typing, but if you're using are a variable or a function name repeatedly.

  • I don't want to scan up the whole document where you explained what the name did, where you could just use the name.

  • Precisely.

  • I can read this code now.

  • Previously, I couldn't if I go back here.

  • Uh, but if I look at this, okay, I know what everything does right away.

  • That's much more useful and much more legible.

  • And if you're writing those comments to explain what a name can do, you're not naming correctly.

  • I love this tweet by Mike Care.

  • I like the rule and functional programming that if it's hard to name, perhaps you're giving the function too much responsibility.

  • Re factoring has helped me name and likewise trying to name has also made my function smaller.

  • The comments are an excuse for not writing the code.

  • Better to begin with and this is the crux of the issue for a lot of people.

  • If you're writing code, that's half hazard, and you're leaning on your cook comments to clarify this means the comments are holding back your programming.

  • This is a kind of course behind the CART scenario, and unfortunately, even as the author, it's kind of hard to distinguish which is which is which.

  • When you're really getting going on a project, we lie to ourselves in myriad ways.

  • Way.

  • Spend time writing a comment that could be better spent, making the code a little cleaner to begin with.

  • We might also tell ourselves we don't need to comment or code because our code is so well written.

  • Even if other people don't agree, Just do your best.

  • There's not one true way when you're writing comments, it's not no comments or yes comments.

  • It's thoughtful comments that are good for the maintainer to read.

  • Try to envision that you're both the author and the reader.

  • When you're looking at that code, when you're writing your code, you're both the the person writing it and the person maintaining it in the future.

  • What information do you need to be as productive as possible.

  • What would a younger you need?

  • It said that 30% of time a developers time is spent writing code and 70% is spent reading code.

  • My suggestion would be to spend a moment after you think you're done with a project in review with commenting eligibility in mind.

  • And I'll even submit P ours to myself when I work alone.

  • I work alone on a lot of open source projects.

  • I learned this from Stacy Covering Mo, and it really helps me look evaluate that code from a new from new eyes.

  • I write it as the person who is just trying to get this stuff done.

  • And then when I submit the PR to myself, I read it as a maintainer and someone who has to maintain the code.

  • Later, I encouraged this practice.

  • More than one thing can be true at a time people tend to get on one side or the other of whether or not you should write comments.

  • But I would argue that the conversation isn't really nuanced enough.

  • Why not both?

  • Hopefully, opening the floor to a deeper conversation about this can help you have right more meaningful comments and bridges the gap.

  • Even so, it could be a lot to parse good hearts.

  • Anyway, I'll leave you with some better humor.

  • Ah, while back there was a stack overflow post where people wrote the best comments that they have ever seen.

  • You could definitely waste some time in here.

  • Here's some here.

  • Some of them that I thought were really good when I wrote this only God and I understood what I was doing.

  • Now only God knows I dedicate all this code all my work to my wife, Darlene, who will have to support me and our three Children in the dog once it gets released into drunk Fixed later.

  • First of images are deleted by G.

  • D.

  • I.

  • Plus second of I'm not sure about that.

  • Some devil on adding temporary tracking of lock in screen.

  • Five years later, I'll leave you with this example that I particularly like from Kelly von.

  • She tweeted this out, saying, sometimes you need to be your own cheerleader if you can't read it.

  • It says this is not a useful comment, but you are useful and you can do this.

  • That's true for all of us to thank you so much.

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

Subtitles and vocabulary

Click the word to look it up Click the word to find further inforamtion about it