Hacker News Reader

Comment by spdy | Hacker News Reader

Interesting my experience was very different when i switched from PHP to Django 5 years ago.

Everything just felt easier, many task where you had to repeat yourself got abstracted away (forms) and the documentation was just awesome one of the main selling points at the time and it still is.

The ORM took me a while to get used to it but after the initial hump i learned it was very powerful and easy to use.

Overall my efficiency went up a lot i was able to prototype in days instead of weeks for feature rich applications. It made me able to toy around with ideas and the first time in my life i had this experience that i hadn't had to fight the framework to get something i wanted.

And you can express yourself so much better in python than php and till today i enjoy the community which is nice and helpful across the board.

View on HN

Well, in CodeIgniter's defense, its documentation was pretty excellent. The problem, however, was the slow and tedious development cycle, which favored backwards-compatibility over new features with almost no exceptions.

I came from Typo3 just to make it short it´s a big mess and only popular because some aspects are easy to sell (i guess).

Why is it that half of everyone says that PHP docs are so much better?

Because of the comment thread at the bottom of each function page... people paste in a common error and how to solve it. The docs are good not because they're written better (though in some cases they are) but because of the user contributed content which the python docs lack. I wish the python docs all has a disqus thread at the bottom.

Python docs have no clear indication what kind of parameters function takes, what values it returns and what happens when it fails:

http://docs.python.org/3/library/binascii.html#binascii.b2a_...

http://php.net/bin2hex

It clearly mentions that it returns a string and that data is binary data. As everywhere in python, when it fails, it raises an Exception.

Sure. Either it says it or it can be inferred from something. But it doesn't have a consistent format. When I'm checking unknown function in PHP I know exactly where to look for descriptions of behavior (also how it fails when it fails and why) and information about type or arguments and return values. And if I need real life use cases I can take a look at the bottom of the page.

In Python function description is often just unscannable short blob of prose.

Like for example http://www.php.net/manual/en/function.ming-keypress.php :P

edit: I feel like the real life examples in the PHP docs are very nice, but not really missing in Python (there are a lot examples in the Python documentation but not for such trivial functions). In python you just start the interactive interpreter and do "import module", "module.function(xyz)" and you see exactly what's going on. It's then a copy&paste away from your shell to your editor.

I'm not saying that PHP docs couldn't be better or more complete. Some (not only but usually less commonly used) modules are barely documented at all.

It's bit strange strange that you gave undocumented function as an example of how PHP functions are documented. :-)

This difference between Python docs and PHP docs is just the thing I noticed when I started having fun with Python which is btw awesome language though finding which lib to use for given task sometimes is hard.

Good thing to do to find out what python function does is running help(module_name.function_name) in interpreter.

I'd say both documentations are very complete but take a different approach. Very often the python standard library is very self-descriptive and it's just doing what you would expect. If you're in doubt you can always start up bpython and have an autocompleted shell. That python has an interactive interpreter really is very convenient.

Reply on news.ycombinator.com