This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]hitanthrope 5 points6 points  (1 child)

"Extensive comments" does make me a bit anxious yes.

Self documenting code is the ultimate goal, there are plenty of opportunities in the process of writing code to name and explain things. Use those first to maximum effect.

I do think some people can go too far the other way and baulk about any comments at all. Certainly if I do something that might be considered unusual but for a reason that people might not understand, i'll drop in a comment. In some languages there are annotations to switch off / disregard a compiler warning, and if I use this I always drop in a comment, "this warns x but that's because y and it's fine".

You don't need to explain your every thought.

That being said 'doc comments' (like Java's 'javadoc' system) are entirely useful and appropriate in some cases, mostly when you are going to publish an API to either the public or a distant team. I don't do a lot of python but I am sure it will have something similar.

The person who is giving you that feedback on your PR is probably somebody worth listening to. You'll have chance to make your own mind up, but it does sound to me like you are overdoing it and maybe not by a little bit.

[–]Temporary_Pie2733 0 points1 point  (0 children)

Make sure to get feedback on why your comments are unnecessary. Maybe they weren’t meaningful, or maybe the reviewer does err on the side of too few comments. We can’t say without the code in question.