I'll tell you whats wrong with python docs. When I google for a function and I see from the search results that the page has exactly what I'm looking for, when I click on the link I am instead presented with a long page of irrelevant information that I then have to filter through. It's so bad that I actively avoid the official docs.
I'd be fine with that if it ended there, but usually the word I'm searching for is in the document in a hundred different places (I forgot to mention that I usually don't know the exact method/object name). It almost always turns into a frustrating process of scanning the page manually.
Well, if you don't know the exact method or object name, how do you expect Google to guess what you need? Let's take a simple example of searching for Python's os.unlink method:
5. Click on os.unlink words because it's an actual link.
That last bit is very important. Every bit of documentation typically has a link from any module/object/method to its canonical documentation location. Contrast this with Django REST Framework, which does not do this and their docs are basically unusable because of this.
I agree that this could be shortened somehow to Google "Python os.unlink" and the first result being https://docs.python.org/2/library/os.html#os.unlink but it's such a minor flaw compared to everything else I've ever seen in terms of searching for docs that I am willing to live with it.
Contrast this with PHP's docs. Here, it's great: just go to http://php.net/YOUR-FUNCTION and you'll get the docs. For example: http://php.net/implode. What I don't like about these docs is that they often lie to your face. As in, they are just plain inaccurate and the way you find this out is by having your production code blow up. That right there is actual bad documentation.
>Well, if you don't know the exact method or object name, how do you expect Google to guess what you need?
I dunno, but google manages to do it pretty well. Like for your example, I might search for "python delete file" since I don't remember unlink. Ignoring the stackoverflow results, the first doc result is the right one, but I'll have a hell of a time finding it on that page. Looking at the next result tutorialspoint, the page itself is exactly what I was looking for. Tutorialspoint is quite excellent in this regard and I've started going there first.
That's a good example. I'd argue that it's very quick to find what you are looking for here. The first result is a Stack Overflow page where the first question links directly to what you are looking for. I definitely can agree that the docs can be better, but at the same time I cannot honestly call them bad. Bad docs are docs that either lie or docs that are not there, and possibly docs that are so ugly they hurt your eyes. Python's docs are anything but.
This is a bit OT, but I started finding Google search results a lot less useful after they shortened the amount of context they quoted.
I think that even in an example like the one you cite, this has some relevance. When the quoted context was larger, it seemed to me easier to find it -- scanning visually -- within the target page.
Of course, there is also the matter that with Google's loosened matching and/or increased page dynamism, results these days pertain less often to what I'm interested in. Not all that infrequently, I'll click through on a promising result, to find little or no hint of the context that Google quoted.
TL;DR: More anecdotal grumbling about the decreasing usefulness of Google search results.
is probably the first thing that pops up when you search of python and tutorial, yet it reads like it is adressed at people that are looking for a way to augment their unix shell. This is not very helpful to most people. Thankfully, there are many alternatives, however it is bad that this is the first thing that pops up.
I am confused by the why is "X so slow" argument. Conceptually and practically, Python might be slower than native C code, but the tradeof lies in the relationship between runtime and "design"-time. It is a little slower, but it is faster to learn, read and write. Demands for "more performance" should be driven by actual numbers: How many people should your webservice serve in a second, minute? So far python has been fast enough for anything I wanted to do. For everything else there is numpy/scipy - fortran for the win!
I am not entirely convinced that there is actually an inherent tension between runtime performance and being fast to learn, read and write. So it might just be that Python is simply slow, and although it has a lot of nice features, the slowness doesn't really have much of an upside.
There is no such tension inherently, yet I have seen a lot of violations of good practices in the name of "more performance". C# might be slower than C++, yes, but the question is: is it fast enough for what I would like to do? The fact that it is garbage collected and doesn't require pointer syntax makes it nicer to use, yet it runs slower. I have made similar experiences with databases, normalization is often discarded due to performance concerns (woohoo, too manz joins). It is true, making a join is slower than not making it, but the performance is gained by having less redundancy checks (I know, I am oversimplifying this). I am just very tired of seeing performance as an infinite target for optimization at the cost of maintainabilty, readability and so on. Exaggeratingly I could state: If you want it REALLY fast, write it in assembly.
Do you see what I mean?
As a follow up on my opinion, here is another item that was recently on hn. Tj Hollowaychuck is leaving node for go, mentioning this discrepancy (runtime focus vs working with it time focus) as a reason
https://news.ycombinator.com/item?id=7987146
Guess: a lot of developers conflate Python documentation with documentation for various Python libraries as found on PyPI. Documentation for these libraries varies from great to "I'll just read the source."
I've actually found myself doing quite a bit of code reading for Django. As much as the team tries, there is quite a bit of undocumented magic that can really trip you up if you are not doing exactly the right things. For example, don't create a source-tree/project/__init__.py file (sibling to your settings.py) that does any type of imports.
I'm going to guess that any dev worthy of the name can discern between a library and core python. I'll allow that I may hold python devs to a standard higher than is realistic (I'm new to using python in my daily work, and not well-versed in how the python community rolls.)
As noted elsewhere, there can be a lot of Ctrl/Command-f'ing to find what you want. That, and sometimes I just want an example of what I have to think is the most common case for a function. Instead I often get examples of esoteric cases that I'll likely never do. I mean, it's nice that those capabilities are there and that they're documented, but I just want to (made-up example) search for a simple ASCII substring, not a UTF-8 substring in a Unicode string using a regex all fourteen optional parameters.
That said, I wouldn't go so far as to say that the docs are bad, but they could certainly be better.
Agreed on the whole, but if we can agree that for ever good developer there are 10x beginners, we can infer that it's the 10x beginners' searches that influence the Google autocomplete.
That's something I love about JavaScript. Most libraries have great documentation, and the source is usually easy to understand. With C#, I feel the opposite is the case. Documentation either doesn't exist or is very basic, reading the source is quite hard because its common to put code in as much files as possible.
Really? I think a lot of people find the opposite to be true about Javascript, in terms of source. Javascript allows for some fun magic, but that pretty quickly cuts into readability/debugability. Look at Bluebird -- works great, but not just a "I'll jump right in here and understand it" sort of module.
You're definitely right about the C# docs, though. I always feel totally lost looking through those, especially since I'm not much of a C# dev to begin with.
I think that if people were more familiar with Smalltalk, the Objective-C would not get that bad rating. I find the Smalltalk message passing syntax is way more readable than more common function(args) syntax. ObjC is nothing more than a plain C with message passing in square brackets.
What might make it less attractive is the verbosity of Cocoa (formerly known as OpenStep), too many class name prefixes, missing native literal objects and use of pointers. This is problem of the framework, not the language itself though.
"why is perlmonks so slow" made me chuckle. Perlmonks is indeed slow (used to be much slower), the user interface is ugly (but quite usable once you got used to it), but it's still the best place for deep discussions about Perl.
If you ask an interesting question (not just "how do join two files on a common column"), you often get several amazing answers.
perlmonks.org lost a lot of credit in my eyes because they store passwords in clear text. All passwords got hacked&leaked in 2009, they notified the users but continue to do it (tried today). This website is run by [any programming language] professionals?
It's a bit amusing that "why is Java so slow" is in there. I have to think that's coming from people who are familiar with Java from the horrible Java browser plug-in rather than server-side Java.
Java is quite fast compared to most languages but for some things it is still terribly slow compared to C / C++. I had to do some big integers crunching lately and tried: Java, Go, Go with GMP, C (GMP) and Haskell (using GMP under the hood). Eventually I went for good old C with the latest GMP version for it was the fastest for my use case (with Haskell and Go with GMP coming close but still not as fast as C).
Java was, for the computation I needed to do... Eight times slower than C! I know I was hitting a edge case for a very specific kind of computation but still. The situation is so bad that there are people who wrote wrappers calling GMP from within Java.
I think some Java devs don't realize how slow some of the Java API are for certain tasks. For example there's no way Java BigInteger can compete with GMP and there's no way GMP is getting ported to Java anytime soon (GMP is open source: just go and look at some of the optimization going on and you'll see what I'm talking about). Most Java devs don't realize how complex and optimized some libraries out there are and how low-level you need to go when you need the utmost performance.
Sure, server-side Java is fast for most things it's used for. But not everything is "server-side" and there are several domains where Java simply doesn't cut it compared to good old C + assembly.
And people finding Java being nearly one order of magnitude slower than the alternative for some tasks may be tempted to ask "Why is Java so slow...".
Now this isn't a criticism of Java: Java is the language I know best and used (and still use) the most. And I know it well enough to know when it's probably a good idea to try to find an alternative.
Java is still relatively sluggish until it gets rolling. Any realistic Java benchmark has to spend a good amount of time just convincing the JVM to start being serious before the benchmarks will give good results. So for people whose use cases look more like "small tool" than "web app," Java can still appear rather slow.
I understand that Java is fast for long running processes that can live in memory. That describes "server-side" environments pretty well but the experience for desktop apps, commandline utilities and many other forms of computing is rather different.
Java takes a long-ass time to fire up and get going. If startup time is significant compared to runtime (as for a command line utility, say), Java can indeed be perceived as very slow.
So far, I've never started typing until I knew what I wanted to ask, so I find them distracting. Sometimes I start reading them and then forget what my own query was.
It looks like some search terms are blocked. If you type "my penis" or "my boobs" nothing happens, but for "my finger" or "my toe" you get some results.
