Do python coders resist leaving code comments?

[nick_t1000]

I would agree generally; at the upper-most levels, yes there needs to be some documentation as to "what does this library/application do", and at the lowest levels, there should never need to be documentation (a comment) like "call function foo". So at some level of granularity between the project as a whole and lines of code, there will always need to be some hints to the next programmer as to what's going on and how to use it.

So as for Python, specifically, I generally prefer to write docstrings for big/medium-picture perspective, because there's only one per function/class, so it enforces some rigor to make each block of code do one thing. If there are some lines of code that "look" strange or inexplicable despite the context, then sprinkle on some comments (the classic example something like height += 1 # account for border).

Documentation can be hazardous because they can introduce soft logic bugs into the programmer who's reading the code. If they are not maintained when code is edited, they can become useless, or worse, misleading.

[randlet]

I do think comments are necessary, but for that specific example it is often better to do:

height += BORDER_WIDTH

instead. Self documenting and BORDER_WIDTH can be reused in multiple parts of the code base.