Code comments: tell me"why,"not"what" - a podcast by Kent C. Dodds

Code comments, they're important you need to have them but what you say in
the code comment is important so I worked at a place where we were startingto transition to ES6 and you know from using var to constant lead and you
know all the new cool features, you know, JavaScript and gotten a lot ofnew and interesting things in a long time and so we're all starting to use
these new things and I saw a lot of comments from some of my coworkersabout like basically describing what the syntax.
Was doing because it was unfamiliar done oh so that was I was installingwith NPM and so in the in the code you would just find all sorts of places
where just described what the syntax was doing because we were we weren't
used to it. I never wrote those comments because those comments were notreally helpful and I would not recommend to anybody write those kinds of
comments and like you could do the same thing for APIs to libraries thatthat you're using that you're not used to like or you know, you could
say,Maybe you have a function component that returns null you could add acomment that says you when you return no it doesn't render anything, you
know, like you just go forever on code comments so it comes down to what isthe code comment actually telling and what's useful about it and yeah like
there there's a difference between a code comment that says what you and
you're doing and it could comment that says why you're doing it and that's
what you really should be focusing on is what you're doing if it needs to
be explained then you should be doing what you're doing a little
differently.Because code comment won't necessarily make it any easier to understand so
yeah, if if your code comment is just saying this assigns the variable rootto the string hello world like that is not gonna be at all useful but you
could explain why you're doing that now you say well our back end expects
us to send a hello world string because of this weird historical factsomething that somebody couldn't just Google and figure out you know, what
it's going on, you know, what with?
With syntax that's something people can figure out but when it comes to
like business domain specific things that's the sort of thing that you want
to write a code comment about it's especially useful when you're default
like what you would expect somebody to do would be X but you can't do that
for reason why and so then you explain why you're doing something that may
not be what people would expect you to be due doing that's what could
comments are for it's to explain why you're doing something that may be
unexpected.I hope that's useful have.A wonderful day.

Further episodes of 3 Minutes with Kent

Further podcasts by Kent C. Dodds

Website of Kent C. Dodds