2010-06-22 01:24 - General

Why I still miss PHP: the manual.

I did PHP programming for around six years. Then I switched to Python full time. There's lots to like, and dislike, on both sides. But right now I want to talk about one thing: the manual.

No language is perfect. You might not remember whether it's replace(haystack, needle) or replace(needle, haystack). So hopefully, looking it up is quick and easy. I'm going to use filter as an example. If you remember that the appropriate function in PHP is array_filter a simple search ( https://www.google.com/search?q=php+array_filter ) finds you the page with the documentation for that function in one click.

How about for python ( https://www.google.com/search?q=python+filter )? You get to the "built in functions" page, which lists over 75 different functions. You can probably Ctrl-F it, which is already a lot more work. There's no examples, and it's generally not as helpful.

Did I pick a bad example? How about date/time stuff? PHP: http://www.php.net/manual/en/ref.datetime.php Python: https://www.google.com/search?q=python+datetime . The second example is the same. PHP docs are full of tables-of-contents, and links to narrow down to the thing you actually want now. Python docs are full of dense pages that have no internal navigation, and a lot more complex and generally confusing details. If I look very carefully (okay, if I Ctrl-F), I can find the strptime documentation for Python. But again PHP has better layout, and more useful information.

Python people: telling me that "This is equivalent to datetime(*(time.strptime(date_string, format)[0:6]))" is not helpful. Telling me "See section strftime() and strptime() Behavior." is not helpful, whereas " The format used in date (e.g. the same as used in strftime()). " (both with the appropriate bits linked) is.


No comments!

Post a comment:

  If you do not have an account to log in to yet, register your own account. You will not enter any personal info and need not supply an email address.

You may use Markdown syntax in the comment, but no HTML. Hints:

  • An empty line between text will create a paragraph boundary.
  • Use angle braces around a plain URL to auto-link it: <http://www.example.com/>.
  • Use this format to create a link with different text showing: [An Example](http://www.example.com/).
  • Use backticks (``), not leading spaces to enclose a code block.

If you are attempting to contact me, ask me a question, etc, please send me a message through the contact form rather than posting a comment here. Thank you. (If you post a comment anyway when it should be a message to me, I'll probably just delete your comment. I don't like clutter.)