Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Python doesn't have a spec. It barely even has documentation nowadays. (Sad. Twenty five years ago it was the gold standard of documenting software.)


Python's documentation today[1] is clearly more expansive, better formatted and more readily comprehensible than its documentation from 2001[2] (or even 2008[3]). There are multiple entire sections of documentation now that didn't exist before. Standards were just lower back then, partly because a larger percentage of "programmers" were accustomed to wrestling with beasts like C, and partly because systems were much smaller.

https://docs.python.org/3/

https://docs.python.org/2.0/

https://docs.python.org/2.5/


Good documentation cannot be "expansive". Good documentation must be a) thorough and b) minimal.

Modern Python documentation is absolutely horrible - there's a shitload of irrelevant rambling while absolutely crucial details are omitted.


Good documentation cannot be "expansive". Good documentation must be a) thorough and b) minimal.

stealing this


and too much casual tone of voice


> Python's documentation today[1] is clearly more expansive, better formatted and more readily comprehensible than its documentation from 2001[2] (or even 2008[3]).

Documentation is not a specification. Specifications cover all behavior that should be expected, and specify which behavior is implementation-defined or undefined. If something isn't defined them this is a failure in the specification that requires fixing. The point of a specification is to allow independent parties to do clean room implementations that can be used interchangeably.


The majority of the comment I was replying to was about documentation, and I was responding to that.


https://docs.python.org/3/reference/grammar.html and https://docs.python.org/3/reference/index.html look pretty comprehensive to me, and they're backed up by a thorough collection of PEPs: https://peps.python.org/pep-0000/

As a relatively recent example, here's the language reference documentation for the match statement https://docs.python.org/3/reference/compound_stmts.html#the-...


That seems uncalled for, the docs are great and the various guides are usually a good starting point to understand and then use the stdlib.


I don’t understand what you mean by “doesn’t have a spec”

The existence of Pypy and CPython and separate but compatible entities shows that there is


CPython is the de-facto reference implementation of Python.

Pypy was developed by reverse engineering CPython and their automated tests feature explicit comparisons with CPyton.

You made the opposite point you thought you were making.


in raku, the test suite (ROAST) is the spec

any compiler that can pass ROAST is valid


> Twenty five years ago it was the gold standard of documenting software.

That was PHP. Though Python was a close second




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: