BRIEFS logo BRIEFS

Code comments: tell me "why," not "what"

02/13/2021 , 2m, 56s

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 starting to 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 of new 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 coworkers about like basically describing what the syntax.

Was doing because it was unfamiliar done oh so that was I was installing with 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 not really 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 that that 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 a comment 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 is the 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 root to 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 fact something 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.