Hi Meghna, I have a few decades of coding experience and I agree with you - write more comments. I tend not to write comments inside a method or function implementation unless the code is unusual, or there are many steps to follow. But I do write function, method, field and class level docs liberally. And I tell my team to do the same. Anything that would appear on a Javadoc page or JSdoc page should be commented well IMO.

I'm sure you've used some libraries that are well documented and you can just treat them like a deterministic black box with ease. Other libraries that aren't documented well (or at all) are much harder to figure out and they just slow you down. Frequently you have to google for examples (where someone else has done the documentation job externally) or worse dig into the library's source code (which can turn out to be like unraveling a thread from the edge of a garment!)

So I tend to err on the side of writing good Javadoc level docs, so that the code can be treated as an easy to use black box. What I often find is that when writing the docs, the assumptions, quirks and complexities come out, so that actually prompts me to improve my code further.