Python code readability

Question

I have a programming experience with statically typed languages. Now writing code in Python I feel difficulties with its readability. Lets say I have a class Host:

class Host(object):
  def __init__(self, name, network_interface):
    self.name = name
    self.network_interface = network_interface

I don't understand from this definition, what "*network_interface*" should be. Is it a string, like "eth0" or is it an instance of a class NetworkInterface? The only way I'm thinking about to solve this is a documenting the code with a "docstring". Something like this:

class Host(object):
  ''' Attributes:
      @name: a string
      @network_interface: an instance of class NetworkInterface'''

Or may be there are name conventions for things like that?

Answer 1

The docstring conventions are at PEP 257.

The example there follows this format for specifying arguments, you can add the types if they matter:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

There was also a rejected PEP for docstrings for attributes ( rather than constructor arguments ).

Answer 2

The most pythonic solution is to document with examples. If possible, state what operations an object must support to be acceptable, rather than a specific type.

class Host(object):
  def __init__(self, name, network_interface)
    """Initialise host with given name and network_interface.

    network_interface -- must support the same operations as NetworkInterface

    >>> network_interface = NetworkInterface()
    >>> host = Host("my_host", network_interface)

    """
    ...

At this point, hook your source up to doctest to make sure your doc examples continue to work in future.

Answer 3

Personally I found very usefull to use pylint to validate my code.

If you follow pylint suggestion almost automatically your code become more readable, you will improve your python writing skills, respect naming conventions. You can also define your own naming conventions and so on. It's very useful specially for a python beginner.

I suggest you to use.

Answer 4

Python, though not as overtly typed as C or Java, is still typed and will throw exceptions if you're doing things with types that simply do not play nice together.

To that end, if you're concerned about your code being used correctly, maintained correctly, etc. simply use docstrings, comments, or even more explicit variable names to indicate what the type should be.

Even better yet, include code that will allow it to handle whichever type it may be passed as long as it yields a usable result.

Answer 5

Using dynamic languages will teach you something about static languages: all the help you got from the static language that you now miss in the dynamic language, it wasn't all that helpful.

To use your example, in a static language, you'd know that the parameter was a string, and in Python you don't. So in Python you write a docstring. And while you're writing it, you realize you had more to say about it than, "it's a string". You need to say what data is in the string, and what format it should have, and what the default is, and something about error conditions.

And then you realize you should have written all that down for your static language as well. Sure, Java would force you know that it was a string, but there's all these other details that need to be specified, and you have to manually do that work in any language.

Answer 6

One benefit of static typing is that types are a form of documentation. When programming in Python, you can document more flexibly and fluently. Of course in your example you want to say that network_interface should implement NetworkInterface, but in many cases the type is obvious from the context, variable name, or by convention, and in these cases by omitting the obvious you can produce more readable code. Common is to describe the meaning of a parameter and implicitly giving the type.

For example:

def Bar(foo, count):
    """Bar the foo the given number of times."""
    ...

This describes the function tersely and precisely. What foo and bar mean will be obvious from context, and that count is a (positive) integer is implicit.

For your example, I'd just mention the type in the document string:

"""Create a named host on the given NetworkInterface."""

This is shorter, more readable, and contains more information than a listing of the types.