1
noder
4y

For those who are on my team, arguing on not putting comments in their code:

How much ever (un)readable your code is, any peer / reviewer / future team member can only understand what that code snippet is doing, but not why was it written in the first place or what the hell you were thinking while writing that logic. So, it'll be awesome if you write that as comments or at least link to the story/design doc which warranted that code.

Comments
  • 1
    In my opinion that is what documentation is for. Explaining your thought process and what the functions are for, not what they do. Any nerd can look at the function and work out what it does but it may not be clear why it's needed.
  • 1
    Comments are for when the code itself cannot explain strange stuff you have to use, like because some mandatory coverity tool is a piece of garbage and demands some pretty stupid demands, of when something is am odd workaround, or some other not obvious stuff which you have to use and explain explicitly.

    For other things code should be explanatory
  • 0
    Depends what we're talking about here. Function/Method and class level comments - almost always, but the line between "comments" and "documentation" there is blurred (said comments almost always being used to production code docs.)

    Inline comments - almost never. If you feel the need to add them then your code isn't clear enough, isn't split up into granular enough parts, or you're underestimating your audience.

    Exceptions always apply of course, but they're general rules.
Add Comment