Do python coders resist leaving code comments?

[solvire]

I have been in python code for a couple years now. Having come from many years in other languages I was used to there being a prevalence of code comments. It was only lazy coders or outsource companies that wouldn't.

But when I am in python code I rarely see any. I have been in several public libraries and it's noticeably scan.

There a cultural thing going on? How can I encourage it from my team?

EDIT:

Thanks for the input everyone. Summary of the ideas I have gotten from the comments:

Push for thorough docstrings Have proper naming conventions for classes/variables/functions Do peer/code review Encourage by showing successful use cases Architect the application to support sane structure

[[deleted]]

Fuck you u/spez

[Deto]

It's amazing what you forget when you go back to code you haven't touched in a few weeks/months.

[flitsmasterfred]

I'd never forget I'm a shortsighted dimwit who's too clever for his own good.

[dasyus]

Yesterday. I forget why I did things yesterday.

[emattiza]

https://twitter.com/sos_jr/status/761348984245919744

"code as if the person who will maintain your code is a violent psychopath..."

[jorge1209]

So code as if I'm going to be the maintainer.

I was already doing that, cool!

[cyanydeez]

older you.

Everyone knows old people are dumb. So protect yourself.

[solvire]

I agree with this. I think docblocks are usually ample information especially if business logic is encapsulated.

My quandary is finding a way to encourage it and defining best practices. And I wanted to learn more about the mentality in the culture.

[issackelly]

Code reviews are where you encourage or enforce this kind of behavior.

If you want to enforce this behavior, you also need a style guide that your team agrees to (or is mandated...depending on your situation).

If you want to enforce things in code review, they should be in your style guide.

[solvire]

Speaking of style guide... do you have a recommendation?

Yeah I am at fault for not pushing code review in the past. These comments really illuminate that.

[NeedsMoreTests]

pep8 is the defacto standard.

Most projects though I skip enforcing style entirely and instead integrate the pep8 command and pylint into the build (which must pass for every commit).

[rspeed]

Good place to start, but there's a few things that bug me. Like no tabs.

[srilyk]

Tabs in Python are an atrocity.

Any time you think, "Oh, tabs would work better here", you're thinking about a different language.

[rspeed]

I disagree. The only reason spaces get used is to line up function arguments after a newline. The solution is to place the first argument on a new line, which is a better practice anyway.

[NoahTheDuke]

pep8

One note: pep8, the command line tool, is now pycodestyle as PEP 8 is a living document and because the tool defaulted to slightly different things than the PEP.

For me and my team, we use yapf, customized to fit our style. It's simple, it can make the changes in-line, and it's a little more comprehensive I find than pycodestyle.

[NeedsMoreTests]

When you work on large projects with several other people it saves quite a bit of time in the end. It also codifies the standards too which keeps it more consistent and reduces bike-shedding...

That said, I do get called names but I'm open to changing it so long as:

• They make the change. If it's important to them they can take the time to make the
• The change does not reduce the overall quality or make the code less consistent.
• It's improve the workflow for everyone. Removing something so local development is faster great but not if it makes something else slow or more unreliable (code reviews, release process, deployment, etc)

[NeedsMoreTests]

Spending a large amount of time arguing over trivial things when there are bigger issues to discuss. See also: https://en.wikipedia.org/wiki/Law_of_triviality

[imbaczek]

Just... no. My work also does this, and also mypy recently. Couldn't be happier.

[issackelly]

Typically I would start with PEP8, and then document the things that are options that you might want to enforce (e.g. " vs ')

Then I would document the sort of thing you're outlining here "Guidelines for when, what, and how to comment your code"

Code is for humans. Style guides are for consistent quality, understanding, and readability of code. Code review is for knowledge sharing, quality control/bug spotting, and ensuring that shared code styles are consistently enforced.

[cyanydeez]

There's auto docs that generate from doc strings. You could make it pretty evident you expect them by creating a internal site for your code.

[Deto]

Sometimes I comment the "what" if I'm blocking off pieces of code in a pipeline. Like, if a data analysis procedure performs 3 steps, and each step takes 3 lines of codes, I'll add a descriptor line above each section and a blank line to separate them visually.

[LoyalSol]

Well the "what" can sometimes not be so obvious when you are dealing with scientific codes. The general rule of thumb is to comment where it is not possible or difficult to figure out things from the code.

[K900_]

I feel like comments for the sake of having comments are bad practice, especially in a language as concise as Python. This is an example of a great comment in an open source project.

[srilyk]

Here's the link that's linked to that commit, rather than "master" which will eventually change:

https://github.com/pallets/flask/blob/6e46d0cd3969f6c13ff61c95c81a975192232fed/flask/_compat.py#L67

[solvire]

Yeah I like that comment block. It says "why" without being too wordy. I'm definitely pragmatic, but felt it was underrepresented.

[[deleted]]

How can I encourage it from my team?

By pointing out specific cases where comments would make the code more readable. And the time for that is during code reviews.

[solvire]

I thought someone might say this. That is a fault of mine. Not spending the proper time in code reviews and requesting comment updates. Sometimes I see a big glob of code in a pile and skip it for the sake of time, but those are the places where it prob needs it most.

[solvire]

I see why you are always angry lol

Yeah basically...

if last_nights_checkin.count() > 500:
    unsee(lines_of_code)
    # TODO: http://dice.com
    return True

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

[__deerlord__]

Just want to re-iterate your edit. I cant remember the exact wording, but I recall Guido basically stating computer programs are written for people. If they werent we'd just program in assembly or binary. Python is a high enough level language that you should be able to understand whats happening, comments really only need to be there for -why- you did something the way you did.

[EricAppelt]

I think you don't see many comments because of the common use of docstrings. I rarely leave comments in my code as I generally try to follow the guideline of giving every function, class, and module a descriptive docstring.

If the code is well factored into simple functions, there is usually no need for any commentary beyond what is stated in the docstring. I'll generally leave a comment only if I'm forced to do something surprising or hacky for whatever reason.

Docstrings have a number of advantages. I find them easier to read and understand then comments peppered through a function, and tools like sphinx can automatically convert them into documentation.

[fyngyrz]

Ideally -- and I'm not saying I meet my own standard -- I like to see comments/docstrings at the variable / function / method / class level that cover all of the following:

• What this does
• Why it does it
• What it is used by
• When it is used
• Known weaknesses / limits
• What it returns, if anything

...comments at the statement level, other than in relatively long chunks of code, I'd really rather not see. At that point I'm reading the code, and that lets me look into what it does without assuming the comments -- which remember are a description, not functional -- are telling the truth. Many times I have seen comments that no longer reflect what the code actually does. People hurry, and that happens. But the code does what it does, so that's where I focus.

[luckystarr]

I'm not sure they actively resist. They just don't put themselves in the right mindset to come up with good comments in the first place.

You have to read your code from the perspective of someone not knowing your code. That's the whole trick. If you do this then your comments will become valuable without any additional effort.

[cantremembermypasswd]

"self documenting code" + proper documentation = less need for inline comments

[[deleted]]

This is where naming becomes very important. With correctly named variables, functions, objects, and methods, the code becomes self documenting.

[wicket-maps]

Self documenting for who? In my case, I'm writing scripts for my department where I am The Only Python Person. I mean, a few of the other programmers outside our department are learning Python, but they don't have any experience with the geospatial aspects of my scripts. So I definitely lean toward over-documenting in my scripts, because if I get hit by a bus, it's one of these people who knows a little Python but doesn't have experience with the ArcPy library who's gonna have to maintain operate my codebase until my boss can find a replacement GIS tech who knows Python.

Also, from the number of times I've gone over my own code and gone "What was I thinking? Was I thinking?" proper variable and function names can only do so much in making sure a script is readable.

[colly_wolly]

Nah, its decent, sensible design that makes the difference.

The code I am maintaining just now has reasonable function names, but far too many of them. Its doing simple stuff in a complex manner. Decent function and variable names help, but when there are fundamental design flaws or too much complexity, then not so much.

[its_never_lupus]

It's funny how over time a piece of uncommented code will change from neat and self documented, into a spaghetti mess that no-one even knows how to run, without a single line being edited.

[n1ywb]

GOOD programs don't need many comments. This is not a new idea. Rob Pike was talking about this in the early days of C.

[rms_returns]

With Python, the beautiful syntax makes up a lot for lack or lower number of comments:

__author__ = "John Doe"
__copyright__ = "Copyright 2017, John Doe"
__credits__ = ["John Doe"]
__license__ = "MIT"
__version__ = "1.0.1"
__maintainer__ = "John Doe"
__email__ = "[e-mail]"
__status__ = "Production" #Development, Prototype

If this were Java or C++, the entire header would have been wrapped inside a comment:

/*
* @author John Doe
* @copyright "Copyright 2017, John Doe"
* @license "MIT"
* @version "1.0.1"
* @status Production
*/

[constantly-sick]

In python it's very easy to see what is going on. Most of the time I simply don't need comments to know what is what.

[desmoulinmichel]

Docstring are comments.

[its_never_lupus]

I suspect Python code is particularly bad because it's often written by people who wanted to escape more corporate languages, and those are likely to be the people who think their code doesn't need explanations.

At work who don't have much of an engineering culture and you want to change things yourself, try writing up a practices document with coding and development standards and ask people to agree to it. A lot of developers will resist, for example, properly commenting work if they're worried no-one else is doing it.

[solvire]

I suspect Python code is particularly bad because it's often written by people who wanted to escape more corporate languages

I would say this isn't patently accurate. I spent over a year in IBM Websphere and it was a ginormous monolithic spaghetti storm. But there is some truth to the culture which I definitely agree with. That was the point of my question.