3 ms·
> I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration.
by hk__2 1y ago
> I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.
It’s standard to write docstrings below the declaration they refer to. What you are refering to are comments, not docstrings. I’ve been programming in Python for 15 years and I learnt this quite recently. This gives you in-editor documentation for class attributes and other non-functions.
- WhyNotHugo 1y agoSphinx reads comments starting with #: above class variables and uses them for documentation. I wonder why they didn’t take the same approach here and invented a new syntax.
- burntsushi 1y agoSphinx is the one who invented new syntax. I just used the syntax Python already had for docstrings, but extended it to variables. Also, when I first wrote pdoc, it was at a time of immense frustration with both Sphinx and reST.
- stuaxo 1y agoBoth sound good, it seems like # immediately above a variable should be the first fallback.
- hk__2 1y agoComments are not included in the AST. Also, Sphinx does support that syntax: https://stackoverflow.com/a/31764368/735926 https://stackoverflow.com/a/31764368/735926