6
A senior dev told me my code comments were useless. Here is what they said.
I used to write comments like // this loops through the array. Stuff that just repeats the code. A guy with 20 years experience looked at my pull request and said your comments should tell me WHY, not WHAT. He gave an example: // retry 3 times because the API sometimes times out after 5 seconds. That clicked for me. Now I only write comments explaining reasoning or edge cases. Has anyone else had a code review that totally changed their commenting style?
2 comments
Log in to join the discussion
Log In2 Comments
wadebailey1mo ago
There is a small thing though about the "what" comments. Sometimes new people reading the code don't know the language or framework well enough yet. Saying // this function formats the date string can actually help someone who has never seen that library before. But for a senior dev on a team that already knows the tools, yeah the why is way more important. It really depends on who is going to read the comments later.
9
joseph5291mo ago
Wow, really? You think reading "formats the date" helps someone who doesn't know the library?
3