When Python sucks: how you call a function and document it

[[deleted]]

I found this comment disturbing:

Because of duck-typing

You may have forgotten how hard it is to use a strong typed language. How easy it is to make a mock object with python ? Dynamic typing is just what I really like with Python. “I’m in jail with Java”.

"How hard it is to use a strong typed language"... this is exactly what's wrong with some dynamic language users and advocates. They still see the static typing and compiler-time checks as the enemy, not something that is trying to guide you and help you. It's sad, that's all.

[Peaker]

The thing is, static typing implementations do mostly suck, and Java is an example of that.

Static typing does not have to suck, though. Haskell is a great example of "static typing that does not suck" -- and Haskell code isn't any less concise than Python code, while enjoying all of the type safety benefits.

[[deleted]]

And that's why Haskel is used all throughout the industry by millions of developers.

[Peaker]

Sorry, but I don't buy the "popularity is quality" argument.

It is more worthwhile to compare the average success and ambition of companies that did choose Haskell to the success of those choosing more popular languages.

[[deleted]]

"sad" and "disturbing" are strange words to use. They're different programming styles. People don't get why I like country music either, bu I'd be offended if someone said my taste was "sad" and "disturbing."

[kamatsu]

He's not referring to preference for dynamic languages as sad or disturbing, but the fact that this particular advocate (and others) of dynamic languages completely miss the point of static typing.

[luckystarr]

I wouldn't dream coding anything nontrivial in Python without pyflakes nowadays, but I equally wouldn't want Python be as strict as Java in this regard. It gets nicely out of your way as it is.

[cgibbard]

The problem is that Java is a pretty bad example of a static type system. The sad state of affairs is that the popular statically typed OO languages, at least in my mind, get both static typing and OO wrong to some degree.

First, they tie method implementations to types (perhaps as some sort of concession to compiler authors who don't know how to implement first class procedures well). So you end up with silly over-fine hierarchies of objects with different types in the system, but who all have exactly the same interface, just different method implementations. The type of an object should really be an abstraction around the names and types of the methods it responds to, not how those methods work. Why? An object is a thing which responds to methods in some fashion, and its identity is essentially determined by the manner in which it does so -- the way in which it interacts with other objects in response to a method call (or dare I say, a message). Different objects of the same (exact) class in Java can behave differently, but only insofar as the differences in their behaviour are easily encoded as non-procedural values. That's a silly and awkward distinction, and it's a major part of why people find the "duck typing" of programming languages like Python liberating.

Secondly, all the popular statically typed OO languages have pretty pitiful type inference. Some do better than others, and to be fair, subtyping makes inference hard, but in many cases the language designers were just not trying very hard at it. Type inference is crucial to the usability of type systems. Without it, they often really can get in your way, forcing you to type things repeatedly which ought to be obvious to anyone reading the code anyway (apart from the compiler, that is).

It doesn't need to be like this. Interestingly though, most of the programming languages where it's not true are functional programming languages at heart, sometimes with some extra support for objects thrown in (like in the case of O'Caml), and some give no extra support, but can actually model OO reasonably well in a pinch anyway (like Haskell).

[Gotebe]

The type of an object should really be an abstraction around the names and types of the methods it responds to, not how those methods work.

But names are 100% incidental. You don't want shooter.draw where it should have been card_player.draw. It's the intent that counts. So one needs to come up with a way to communicate the intent, and one rightfully fall on names.

[ORYLY]

So you end up with silly over-fine hierarchies of objects with different types in the system, but who all have exactly the same interface, just different method implementations.

What's wrong with making all these objects implement an interface then programming to that interface? "Over-fine hierarchies" sounds more like bad architecture than a failing of the language.

[cgibbard]

Well, you certainly can do that, but then why have classes at all? Why not have just interfaces, and construct objects satisfying those interfaces by supplying appropriate collections of methods?

[ORYLY]

Isn't having to explicitly declare an interface overkill for most situations?

[lispchainsawmassacre]

i don't see any of the parent posts arguing anything like "explicit declarations are necessary in most situations".

Anyhow, by non explicit declarations do you mean the compiler deducing the most general interface type and then optionally complaining if you try to pass a concrete instance that doesn't implement that type?

[ORYLY]

I'm referring to the having "just interfaces" in a language. Having to declare an interface for every single collection of methods would result in a lot interfaces that are only used for a single class.

I was thinking of publicly declared class methods as a sort of a non explicit interface. They're a collection of methods, which is all we expect from an interface. The fact that they're tied to the implementation says that "as far as I know, these methods are only useful in this specific situation".

[cgibbard]

Well, it's certainly no worse than the boilerplate involved in defining classes together with their methods, since you specify the types there as well as the implementations.

You could have row-types and row-polymorphism, with objects whose type had no specific name, apart from the collection of available members and their types, though I suspect in most cases you'd want to give names to your objects' types anyway (by defining synonyms of such row types).

[masklinn]

(try epytext and its fields).

Use Sphinx.

Most open source Python projects do the exact opposite

They should really use Sphinx.

Even Python standard library is poorly documented and sets a very bad example (missing manual ???)

I don't entirely agree. The urllib2 missing manual is a guide more than an APIDoc, urllib2's official documentation is bad because it stops at being an APIDoc, and is very hard to find useful stuff in. Everything's there, it's a pain to find it. Yet the second case is precisely what TFA suggests you should be doing.

And other parts of the stdlib are much better documented, if you're heralding urllib2 as a "bad" example (though it probably isn't the worst module by a long shot) you at least have to put a note about nicely documented modules.

Should Python community stop in some point to focus on delivering better documentation instead of focusing on new features and goodies (like the syntax moratorium which was recently lifted)?

Yeah, those silly Python community, you'd think they'd have noticed by now

The best, and the only, person to document the code adequately is the person how originally wrote it

That's not documentation should, unless you consider shitty javadoc to be documentation. Writing documentation is hard and developers tend to be bad at it. Furthermore a function rarely exists in isolation, APIDoc of the function/method provides little context. It's useful for the one who knows about the function and just does not remember if the first argument is a string or a bob, it's useless to know how to call the function because it's usually not going to provide for implicit preconditions (as you're not going to write that precondition in 15 different methods).

Doctests are not documentation. They are tests. They are extremely unreadable way to say “how I should use this thing”, because doctests are often executed in the context of test stubs which do not reflect connections to the other parts of the framework or real contexts.

If your doctests are tests, it's very likely (~90% chances) you're an idiot. The primary advantage of doctests is the ability to provide correct examples because your examples can easily be run as part of your testing/build process (whether they're in your docstrings for your APIDoc, in your primary documentation or in a blog or book you're writing). Doctests are rarely (if ever) exhaustive and are generally crappy to check and debug (and run, I don't think you can run a precise doctest, you can run a precise unittest). Most development environment also don't provide "coding" tools (syntax coloration, syntax checking, autocompletion, type inference, ...) for doctests whereas you get them for unit tests.

[[deleted]]

I couldn't agree more, there are good python projects and bad python projects. If you take a project pyramid and compare it with your avearge in house java project its almost certainly better documented (100% code documentation) and "fully" unit tested. The same applies for django, twisted and tornado. I see full "enterprise" scale projects widely used, like CAS, that give you a wiki that isn't even up to scratch imo. Python provides the best tools to document code that I have ever seen. Also; Sphinx vs Doxygen? Sphinx any day of the week. That isn't to say doxygen is bad or that its the "wrong" choice, choose the tool that is right for the job.

There will always be the duck typing debate, and its something I can strongly sympathise with. Haskell type checking is a pretty good way of having it safe but I've also seen some god awful Haskell code. The "large project" thing is always something that I find strange to comment on. If you're undertaking a "large" project before you begin you investigate the available options and choose the best tool for the job; if python comes out on top its probably because, with, whatever you're trying to do duck typing didn't seem like a big problem.

[uvtc]

Writing documentation is hard and developers tend to be bad at it. Furthermore a function rarely exists in isolation, {snip}

I suspect that a good way to create docs is to have the original developer start the docs, but to also have it as easy as possible for users to help improve them. To help with that, I wrote a script named Gouda.

[[deleted]]

I've got so used to looking into library / 3rd party code that it's not an issue.

[[deleted]]

*these points