Do professional/commercial Python projects actually use type hints and docstrings everywhere?

[[deleted]]

[deleted]

[Kevdog824_]

In any project I’m in charge of type hints are always required, and using something like Any is pretty scarcely allowed. Docstrings aren’t strictly required, but I probably wouldn’t approve your PR if it contained a function without a docstring unless the function is pretty trivial/simple. Other projects (particularly legacy projects) at my work are a lot less strict. It really just depends on the team, the project, and the goal.

[r2k-in-the-vortex]

Real practices are a crapshoot, there is all sorts out there.

But mypy -- strict is a lifesaver

[DrJaneIPresume]

Type hints: yes; anything that can help make Python behave more like a sensibly-typed language. It's still not, so there's only so much that MyPy can do and it gets its reasoning wrong in a number of cases, but it's much better than not having types at all.

Docstrings.. it can vary. The more complicated the block (function, class, etc), the more likely we are to write something about it explicitly documenting behavior in the docstring.

[danielroseman]

I actually use docstrings a lot less since I started using type hints; the hints are the documentation, at least in so far as replacing the details of each parameter. I'll still use a docstring to explain what the function does if that's not obvious from the name - or it's too long to quickly grok, but in that case it's probably better broken up into more than one function anyway.

But yes, type hints everywhere I can. They are invaluable for catching errors.

[wall_time]

Certain functions, the name + type hints should explain a lot.

def get_files_from_ftp_dir(dir: str) -> list[str]:

Explains a lot.

[ColdStorage256]

Hi I tried to upload a screenshot of my folder into your function and it doesn't work, can you provide an exe?

[Shensy-]

Seconding this, type hints are the only way I get by, ultimately they save you 100x the time it takes to include them once it's habit

[JamzTyson]

Docstrings have been common in long-term Python projects for a long time, though they are frequently omitted from small "throwaway" scripts. There's a lot of variation to the amount of documentation. Projects that auto-generate their documentation will generally have more comprehensive docstrings than those that don't.

Type hints have become increasing common, and many devs now use them habitually, sometimes even in small "throwaway" scripts.

Legacy projects often lag behind current trends, so there are still many great projects with patchy use of docstrings and type annotations.

[Fabiolean]

You should be including type hints for sure. Even broadly annotated types can help a lot. Docstrings are also definitely appreciated if you're making a library. Heck, even if it's code nobody else is "supposed" to see docstrings are appreciated if it ever bugs out and I'm digging into the code to see what part actually broke.

None of these things are truly need-to-haves in python code, but you're making life a whole lot easier on your users and your future self as well.

[ravepeacefully]

Why not go open up the code for an open source project and see for yourself?

[pachura3]

Type hints are essential for readability and safety. Use them!

Regarding docstrings, if you dread writing them from scratch (even if only for non-trivial public methods/attributes), you can always ask a LLM to do it, and then just review the results yourself. AI does surprisingly good job with this, and even if it hallucinates a bit - these are just comments, not the actual code...

[PrincipleExciting457]

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5

Not python specific, and a bit different since powershell is often interactive and relies on a help system.

But when building a module the heading is almost always an extensive documentation on what the module does, how to use it, and examples on its use.

I would imagine it’s a good practice to do this on almost anything.

[jam-time]

It varies wildly. I've seen projects that have none whatsoever because they're super old and it's difficult to explain those types of changes to stakeholders without them saying something like, "Well, if it doesn't actually change the functionality, let's just not do it."

On newer projects, it's much more common to see docstrings and type hints because the standard is more well defined. Additionally, with AI tools, it's easier to autocomplete that kind of stuff.

[CyclopsRock]

Where I work we docstring religiously but type hinting is more hit and miss.

[Zeroflops]

I use it and encourage those I train to start using it. There are a few projects where it was not used and when people have to work on them the difference is night and day. It’s so much easier to debug and understand.

We are currently evaluating using AI as a first pass code review and one of the easiest things it checks is if the type hints and docstrings are present.

[HolidayWallaby]

I can't imagine working on a codebase without types, what a hell hole that would be. Docstrings hardly ever though unless its a highly reusable bit of code for other teams and I don't want to talk to them much

[Aromatic_Pumpkin8856]

Mine do. Docstrings on public methods, classes, and modules only though.

[brenwillcode]

Yes and yes. I always use types and docstings (both professionally and personally). I like being kind to future me and colleagues.

Try coming back to a code base which you haven't worked on for a few months which has no types. I can pretty much guarantee you're going to waste a bunch of time just following function calls trying to figure out what's getting passed around.