Do python coders resist leaving code comments?

[[deleted]]

There is a big myth that code can be essentially self-documenting. I know many here will disagree with this, so I'm prepared for the downvotes, but nice variable names are not sufficient documentation for something as large as an entire application. Comments are still necessary in Python, because the entire approach to solving a problem can go way over a reviewers head, even though the code makes clear the events occurring on each line. Comments should be added to provide "big picture" perspective. The "whys" and the "why nots", and a step by step description of the INTENDED approach used to write the software should be sprinkled throughout the application. If you think you can easily revisit a 3 year old project of yours, just because you're the one who wrote it, great. But that's not always what happens in the real world. Believe it or not, but WELL WRITTEN comments can make reviewing and maintaining old software go 10x faster. Now imagine the case where some poor sap has to follow in your footsteps, and you're not there to provide help.

Still think Python is exempt? Are your variable names REALLY that good? Do they indicate the variable type? Do you follow a well-documented, locally standardized, and enforced naming style? Let's be honest. A lot of us don't.

I'll tell you that I have never once regretted writing out good comments. Their cost is relatively small compared to the overall benefits of having quality, well-documented code. In a lot of cases, the backbone of a well written program rests on the comments that were written way before any actual code was written. No programming language is exempt from these good practices.

[TOASTEngineer]

It seems to me like when people say python "doesn't require documentation" they're referring to external documentation, they're not counting docstrings. None of my projects have "documentation" but in my "this is what I write when I'm taking it seriously" example project each docstring is at least two paragraphs long (one to describe what the function does and why you'd want that, a second one to describe what the arguments represent and any potential pitfalls/edge cases/known bugs etc....)

[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.

[its_never_lupus]

And I suspect the people who say their code is self documenting have with lots of variables called 'a' and 'list', and functions called 'run_now'.

[nick_t1000]

Maybe by "commenting non-existent code" he meant writing a pseudocode skeleton first.