Hacker News Reader

Comment by ge96 | Hacker News Reader

Is that an anti-pattern to put the comment inside the function vs above

Function documentation goes inside functions in Python, explicitly making them self-documenting. That can then be automatically picked up by any other code (like tooling for automatically generating API documentation) formalized as PEP 257, https://peps.python.org/pep-0257

Python will literally assign the content of your docstring (a triple-quoted string at the start of a function) to a special double underscored ("dunder") property called `__doc__` that any code can access; not just docs generators, but your own code as well (pretty dang useful for generating on-the-fly help output!).

Which also means that if you run into weird behaviour where a function doesn't do what you think it should do, you can just fire up the REPL, import that function, type `print(function_name.__doc__)` and presto, you have the documentation right there, specifically for the exact version you're using. You don't even need to leave your IDE if it comes with an integrated terminal.

> Python will literally assign the content of your docstring (a triple-quoted string at the start of a function)

Any string. Triple-quoted is just multiline strings and works anywhere.

True, I forget some people think a single line is function documentation; any function that's worth documenting is worth documenting properly, and needs multiline ;)

> type `print(function_name.__doc__)`

Or even easier: `help(function_name)`!

https://news.ycombinator.com/item?id=43266546 just got posted about that =D

How is this not more well known? I thought I was a god for discovering dir() but you’re showing that I was nothing but a peon!!!

There's a bunch of "all dunder properties" pages online, any one of them is well worth reading through at least once. So much hidden goodness.

The actual docs on python.org are quite readable and probably a lot more accurate than random blogspam / LLM glurge pages

Why would you assume it's LLM slop when Python's been around for decades? Lots of folks are enthusiastic enough about "Python magic" to have done excellent writeups of literally ever dunder function under the sun on a single page, at a level of detail and excellence that the python documentation, bless its heart, cannot ever hope to match.

- The python docs are there to give you the information you need.

- Passion pages are there to do a deep dive into all the crazy shit you can do with that information =D

Annoyingly it pushes the type definitions away from the function body when you have a particularly long doc. It’s a cute trick but docs above would have been better.

You know what's cool: IDEs. They can do block folding. The really good ones just auto-fold function docs because you don't need to see those until you do.

It's not just a good trick: it's the right way to do it, and tooling can be (trivially) made to show you only what you need to see until you need to see more.

If we’re assuming an IDE that can arbitrarily change text layout and rendering I don’t see why it matters where the comment goes

TIL __doc__! Pretty nifty.

interesting TIL too bad we don't have auto doc gen (fastapi what I'm working with atm)

edit: not saying it can't be done but our org isn't using auto docs

Yeah, it's one of those "Once you're used to writing doc strings, you have no reason to ever use anything else" but if you don't use them, it can be prohibitively laborious to move whatever alternative you're using over to "PEP-compliant".

(lots of fun dunder functions in Python that make metaprogramming a lot easier, but someone needs to tell you about)

Fluent Python covers a bunch of this stuff.

Reply on news.ycombinator.com