This course has been updated! We now recommend you take the Complete Intro to Web Development, v3 course.
Transcript from the "HTML Comments" Lesson
[00:00:00]
>> Brian Holt: Let's talk about Comments.
>> Brian Holt: So, we as coders and as human beings are forgetful bunch of people. We do something, and then we totally forget why we did it [LAUGH]. I'm speaking very much from personal experience, because I do things all the time that I cannot remember why I did it.
[00:00:22] And particularly, if you asked me to look at code that I wrote last week, I cannot remember exactly why, or how things worked. Because I write too much things, I do too many things, I just can't keep it all in my head. Usually, I try and write HTML, and CSS, and JavaScript that I would call self-descriptive, so that you look at it and just by looking at the code you understand what it does.
[00:00:44] That is the goal, that's the Holy Grail, that's always what we're looking for, is self-describing code. The code reads like it executes. This is not always possible, but you can't always have code like that. Sometimes you need code to be a little bit more clever, or it's just really, really complicated.
[00:01:05] For variety of reasons, your code will not describe itselves in various different ways. The remedy to this problem is comments, right? So in HTML, you have the ability to leave comments, and they look like these.
>> Brian Holt: Now if I go up here to where I had all the stuff with the table.
[00:01:30] If I put a comment,
>> Brian Holt: Here.
>> Brian Holt: This is a comment.
>> Brian Holt: I'll talk about that in just a second. This is my font that does this [LAUGH]. My font combines things together. So this is actually an angle bracket with two dashes next to it, and my font just combines it together to make it look like an arrow.
[00:02:04] Anyway, same thing here, this is actually exclamation point dash dash, but when it does that, it combines it together. That's just my font doing, there's nothing special about it. Anyway, so this is a comment right here. You'll notice that this doesn't actually show up here at all despite the fact that this is being rendered out here.
[00:02:23] That's the point of comments, is that they don't actually end up being shown to the end user. It's purely for the programmer behind it. In fact, if we went and looked at the way this code is looking, I'll show you how. Where do we go? Down, down, right there.
[00:02:46]
>> Brian Holt: So, I'm actually browsing. This is really hard to see.
>> Brian Holt: Let's switch that to be like that.
>> Brian Holt: So I'm gonna go through my HTML right here. We'll just look at this one right here. So that line that I have highlighted there, that's not being displayed anywhere.
[00:03:15] It's just a comment, it's actually for the framework that's running this website called React. That's what it's outputting there. But this is just a comment that's being put out there, and it's not rendered anywhere. it's purely for the programmer and the, so that's what that does. It's a way for you to leave comments, like hey, I did this for this reason, or I put this here for this reason.
[00:03:38] It's for you to leave basically a post-it note to your future self, or to your future colleague, as well.
>> Brian Holt: Again, we're writing code to try and make it maintainable. Cuz it doesn't take a ton of time to write code, but you will spend a lot of time maintaining the code that you write.
[00:03:59] And so that's ultimately what we're trying to optimize for. We're not trying to optimize for writing code as fast as possible, or for being as clever, or for being as terse as possible. We're writing code, so that we can maintain it in the future. Cuz inevitably, your code has bugs.
[00:04:14] We just break stuff all the time. And so you want to make it so when you come back, when something is broken or when you need to change something that you can understand it as quickly as possible. You can kind of formulate like this is what this system is, inside of your brain.
[00:04:28] And then you can make the changes that you need and then move on. So spend time getting it right, right? Spend time making it maintainable, spend time making it readable, make code readable. If I can give you one piece of advice as one coder to another, make code readable, make code understandable, don't be clever.
[00:04:49] Its fun to be clever, and do that on your own damn time, not my time [LAUGH]. So, that's what comments are for, they're like little post-it notes. However, don't go overboard with comments. So the danger with comments is that oftentimes, a coder will go back in and change something, right?
[00:05:12] And then, but not delete the comments. And so, you have these comments that are super out of date, that used to apply to old codes, but still are floating around in your code. And that's terrible, because someone is gonna go, they're gonna read the comment and like okay, these does this, and then they're gonna go read the codes, it's like wait, no.
[00:05:29] It doesn't do that, right? And so you actually end up wasting even more time, because you helped the future person make an assumption about something, and the assumption was wrong. So that's a huge problem too. So be sparing with comments, I think is my next piece of advice for you.
[00:05:50]
>> Brian Holt: And then something like this, if I have an h1 right here, right, and then right after I put the title. This is not helpful, right? This is not helpful because if I look at this, I damn well know that's the title of article. I don't mean some comments telling me that's the article, right?
[00:06:07] It's just like okay, thank you captain obvious. Yeah, I can figure that out. So, use comments when the code fails to describe what it does. I think that's kind of the best way to put it. [COUGH] I have arguments with people all the time about how many comments to leave.
[00:06:28] Ideally, in far on the like less side, like use comments only when they're absolutely necessary. Whereas some of my colleagues at Netflix were much more like, comments everything. So that's a stylistic choice, as well. I leave it up to you. You should leave some comments. I think that's a base layer.
[00:06:49] But I comment far less things. And I spend more time trying to write code readable, but anyway.
>> Brian Holt: So this is me calling out Gem Young. [LAUGH] He's another Frontend Masters teacher. My way of writing comments is better, that's what I'm trying to say [LAUGH]. I'm pretty sure he's not listening, so I can say that.