The First Rule of Comments in Code

// 😧 Sometimes I believe the compiler ignores all my comments
/* Comments have the tendency to become unhelpful: outdated and incorrect. Why does this happen, and what to do about it? 🤔 */
0:00 Intro
0:17 Unhelpful
3:29 The first rule
4:12 How to avoid comments

[@markusfreericks5766]

Comments are useful to explain the "why" of a function, or a data structure; commenting the "how" should not be necessary when variables and functions are well named.

[@GerardoFurtado]

Great points. We all write comments to other people, but because I work in a small JavaScript team (it's only me!), I normally write comments to a special kind of other people: myself in the future. Sometimes I am told to refactor a code I wrote months or years ago, and it's like someone else wrote it, I have to spend time reading it and remembering its flow... in these cases the comments from my old self are really helpful.

[@thomvandenhil4717]

You truly deserve more recognition for the amazing content you create. Keep up the good work!

[@EnergyCreator05]

Comment why not how.

[@SRG-Learn-Code]

I love to find comments in repos I want to use. You might (no, you absolutely are) be a better code than me and just understand what is happening, but I need those comments to follow.

[@Fearthelettuce]

I tried to leave a comment, but then you told me that comments were bad...

[@dapodix]

Love this - it resonates so much with me having to explain these to trammates who seem to fear the absence of comments. If only this video was available in a blog post form for reference? 🤔

[@branvandermeer]

@dapodix: I just published the article version of the same content on my website!

[@goosydev]

Exactly, i see too many videos explaining how to write good comments, while that still brings value when you really need to write comments, most are really unnecessary. I think the only good place to comment is when you're learning something new, especially when you're new to programming. Otherwise I try to avoid them entirely because they are so unpredictable and from my experience almost always wrong.

[@SRG-Learn-Code]

What if you make Jsdocs works like typescript? Are you testing your comments?\

[@principleshipcoleoid8095]

1:08 rust has doc comments that can be tested :p

[@branvandermeer]

Sure, fair enough. But most of us are mere mortals, not using rust for our day jobs ;) ... and not the whole comment can be tested.