DEV Community

Discussion on: Don’t comment your code

abhinav1217 profile image
Abhinav Kulshreshtha

I disagree about Javadocs being clutter. IDE parse these comments to provide meaningful help and autocompletes. And when generating documentations, these comments are parsed.
Javadocs/Docblocks are and should be only proper comments in code. Take any kotlin std file, they have some really proper comments. And from personal experience, ever since I properly learnt about js-docs, both mine and people who I work with have their life simplified.
Ofcourse this doesn't mean I am against other types of comments, and I agree that if those aren't properly written, they become noise.

I think a very big issue is that there are all these amazing courses in schools, colleges and Youtube, preparing you to become a good programmer, but none put emphasizes on proper etiquette on code comments, naming standards etc. I remember when I first got a large multi-team, multi-language project, I realized how easy is it to mis-manage project because of lack of guidelines on these. There were written guidelines on how to name functions and where to put certain files, but there were nothing on supposed non-trivial stuff like commenting etiquette, and most of the issues we faced on daily basis was related to this.