7 ms·

I wonder what the reason is to include code in a release without documenting it. Maybe this article can form the basis for finally documenting this feature? Th

I wonder what the reason is to include code in a release without documenting it. Maybe this article can form the basis for finally documenting this feature? There's also the reverse with Python: useful code in the documentation not included in the standard library.

HerpDerpLerp 11y ago
Maybe this sort of thing will be tackled by the new stackoverflow documentation thing. This link may do nothing if you are not part of the beta! http://docs-beta.stackexchange.com/documentation http://docs-beta.stackexchange.com/documentation
creshal 11y ago
> I wonder what the reason is to include code in a release without documenting it. Presumably it's considered an implementation detail and the author didn't realize it was useful for anything else.
- dalke 11y ago
  The author knows that it's useful. See http://effbot.org/zone/xml-scanner.htm http://effbot.org/zone/xml-scanner.htm where the author uses the scanner: > The 2.0 engine provides another (undocumented) feature that can be used to optimize this even further. The scanner method is used to create a scanner object and attach it to a string. See http://bugs.python.org/issue5337 http://bugs.python.org/issue5337 where the Python developers wondered if it should be documented. There's a 10 year old notice at https://mail.python.org/pipermail/patches/2006-November/021090.html https://mail.python.org/pipermail/patches/2006-November/0210... saying that the code would crash if the scanner was called from multiple threads. There's no doubt much more information about this - the above was all I cared to find out.
notzorbo2 11y ago
This happens pretty often in the Python world. There's a bit of an unwritten rule to leave implementation details public that would be private in other languages. Many libraries simply don't bother with prefixing privates with '_' and just leave things undocumented that you probably shouldn't touch/use. One notable example is importing libraries in your code automatically exposes them to the caller. $ cat lib.py import re def somefunc(): pass $ python >>> import lib >>> lib.re <module 're' from '/usr/lib/python2.7/re.pyc'> Many packages also do `import *` from files which polutes the package namespace with all kinds of stuff you really don't want in there. For example, the popular Requests package: >>> import requests >>> requests.logging <module 'logging' from '/usr/lib/python2.7/logging/__init__.pyc'> The logging module is not a public part of requests' API. It's just there because requests uses it internally. So to answer your question, I'd say it's just common practice. If it's undocumented in Python, you should pretend it doesn't exist.
- orf 11y ago
  Importing libraries from other libraries like this is very useful: $ python >>> import lib >>> lib.re That's how __init__.py files work, and is part of what makes Python awesome. Using `import *` is very bad practice in modules (except in very specific cases) because it brings in a bunch of crap you don't want and didn't expect. Modules should define a '__all__' list of 'public things' you want to export, but restricting access is very anti-python as we're all consenting adults. If it's undocumented in Python, you should pretend it doesn't exist. I don't agree. It's fairly common to dive into 3rd party packages code to see what's occurring and to use 'undocumented' things (which is mostly because the documentation is bad rather than being hidden away). Just look at the Django `_meta` API, which people relied on because it was the only place you could get some specific model information in a stable way, despite being undocumented and private. Now it's been formalized into a proper API. Pythons extensive use of duck typing also makes it a lot easier to work with undocumented stuff, you can make some wide ranging changes to internals (changing types completely, turning properties into functions) but as long as it quacks roughly the same nothing breaks.
  - andreasvc 11y ago
    What is useful about 'import lib; lib.re'? I cannot think of a situation in which a direct important wouldn't be better, while that has many obvious advantages. The __init__.py is a special case of course, but you would only use that for a package's own modules. > It's fairly common to dive into 3rd party packages code to see what's occurring and to use 'undocumented' things It may be common, but it doesn't convince me that it's a good idea. It seems to me that it would be better if the language forces you to design the public API properly, than to resort to using undocumented/private APIs.
    - maxerickson 11y ago
      How can the language force good design? Like how would a language that uses explicit exports stop someone exporting everything? I agree that accessing libraries indirectly probably isn't useful, but I think being able to do dir(lib) and see the namespace that is in use is a good thing (at least in the context of Python).
rjprins 11y ago
Imho, (good) Python code is so easy to read and inspect, that it can be better than documentation. Documentation is less exact. I often find myself reading the libraries that I use, to see what it really does. Once you get into the habit of that, documentation is only useful as a starting point and you can discover a lot more useful functionality. (And also get a good feel of the quality of the library, and learn a lot in terms of patterns) Of course, this habit comes with the risk that you might have to do more maintenance on your code on library updates. As documentation takes effort to write and constitutes a sort of contract with your users, it makes sense for library writers to only document the truly essential.
- andreasvc 11y ago
  I don't think this position of relying on code instead of documentation is tenable for non-trivial code. The amount of effort to understand code is generally much more than that of maintaining documentation of what a function does, meaning of arguments, and any assumptions made. Documentation can (and should) have a much higher signal-to-noise ratio.

HerpDerpLerp 11y ago

Maybe this sort of thing will be tackled by the new stackoverflow documentation thing. This link may do nothing if you are not part of the beta! http://docs-beta.stackexchange.com/documentation http://docs-beta.stackexchange.com/documentation

creshal 11y ago

> I wonder what the reason is to include code in a release without documenting it. Presumably it's considered an implementation detail and the author didn't realize it was useful for anything else.

dalke 11y ago
The author knows that it's useful. See http://effbot.org/zone/xml-scanner.htm http://effbot.org/zone/xml-scanner.htm where the author uses the scanner: > The 2.0 engine provides another (undocumented) feature that can be used to optimize this even further. The scanner method is used to create a scanner object and attach it to a string. See http://bugs.python.org/issue5337 http://bugs.python.org/issue5337 where the Python developers wondered if it should be documented. There's a 10 year old notice at https://mail.python.org/pipermail/patches/2006-November/021090.html https://mail.python.org/pipermail/patches/2006-November/0210... saying that the code would crash if the scanner was called from multiple threads. There's no doubt much more information about this - the above was all I cared to find out.

notzorbo2 11y ago

This happens pretty often in the Python world. There's a bit of an unwritten rule to leave implementation details public that would be private in other languages. Many libraries simply don't bother with prefixing privates with '_' and just leave things undocumented that you probably shouldn't touch/use. One notable example is importing libraries in your code automatically exposes them to the caller. $ cat lib.py import re def somefunc(): pass $ python >>> import lib >>> lib.re <module 're' from '/usr/lib/python2.7/re.pyc'> Many packages also do `import *` from files which polutes the package namespace with all kinds of stuff you really don't want in there. For example, the popular Requests package: >>> import requests >>> requests.logging <module 'logging' from '/usr/lib/python2.7/logging/__init__.pyc'> The logging module is not a public part of requests' API. It's just there because requests uses it internally. So to answer your question, I'd say it's just common practice. If it's undocumented in Python, you should pretend it doesn't exist.

orf 11y ago
Importing libraries from other libraries like this is very useful: $ python >>> import lib >>> lib.re That's how __init__.py files work, and is part of what makes Python awesome. Using `import *` is very bad practice in modules (except in very specific cases) because it brings in a bunch of crap you don't want and didn't expect. Modules should define a '__all__' list of 'public things' you want to export, but restricting access is very anti-python as we're all consenting adults. If it's undocumented in Python, you should pretend it doesn't exist. I don't agree. It's fairly common to dive into 3rd party packages code to see what's occurring and to use 'undocumented' things (which is mostly because the documentation is bad rather than being hidden away). Just look at the Django `_meta` API, which people relied on because it was the only place you could get some specific model information in a stable way, despite being undocumented and private. Now it's been formalized into a proper API. Pythons extensive use of duck typing also makes it a lot easier to work with undocumented stuff, you can make some wide ranging changes to internals (changing types completely, turning properties into functions) but as long as it quacks roughly the same nothing breaks.
- andreasvc 11y ago
  What is useful about 'import lib; lib.re'? I cannot think of a situation in which a direct important wouldn't be better, while that has many obvious advantages. The __init__.py is a special case of course, but you would only use that for a package's own modules. > It's fairly common to dive into 3rd party packages code to see what's occurring and to use 'undocumented' things It may be common, but it doesn't convince me that it's a good idea. It seems to me that it would be better if the language forces you to design the public API properly, than to resort to using undocumented/private APIs.
  - maxerickson 11y ago
    How can the language force good design? Like how would a language that uses explicit exports stop someone exporting everything? I agree that accessing libraries indirectly probably isn't useful, but I think being able to do dir(lib) and see the namespace that is in use is a good thing (at least in the context of Python).

rjprins 11y ago

Imho, (good) Python code is so easy to read and inspect, that it can be better than documentation. Documentation is less exact. I often find myself reading the libraries that I use, to see what it really does. Once you get into the habit of that, documentation is only useful as a starting point and you can discover a lot more useful functionality. (And also get a good feel of the quality of the library, and learn a lot in terms of patterns) Of course, this habit comes with the risk that you might have to do more maintenance on your code on library updates. As documentation takes effort to write and constitutes a sort of contract with your users, it makes sense for library writers to only document the truly essential.

andreasvc 11y ago
I don't think this position of relying on code instead of documentation is tenable for non-trivial code. The amount of effort to understand code is generally much more than that of maintaining documentation of what a function does, meaning of arguments, and any assumptions made. Documentation can (and should) have a much higher signal-to-noise ratio.