Written for people first: readability, indentation and great Python code

Great Python code is written for people first. A program has two audiences at once: the computer that runs it and the programmers who must read, debug and improve it. That is why Python's style guide holds that readability counts, and why the language makes indentation part of its grammar.

Guido van Rossum, who started Python, explains that a program is like a recipe that must be completely unambiguous, because computers lack human context. But unlike a cookbook recipe printed once and followed in kitchens, software is so complex that you don't get it all right at once, so it is debugged and improved continually by teams or by its original author. In his words, "software is a very social activity." Even a lone programmer, he says, would be wise to adopt formatting conventions. He compares indentation to the layout of a good cookbook: crunch a recipe into one solid block of text and a cook can't tell where one step ends and the next begins. In a green field he would still choose indentation over braces, because it reduces clutter, frees up brackets for other uses and spares beginners fights with syntax.

Chris Lattner, who is building Mojo as a superset of Python, defends the same indentation on practical grounds. Brace languages end up run through automatic formatters anyway, misleading indentation, where the layout says one thing and the braces another, has caused notorious bugs, and one notion of grouping removes clutter and a whole design space of rules. Mojo keeps indentation, and proposals for braces get a polite no. His broader aim is to meet programmers where they are rather than force them to rewrite their code, while adding the speed Python lacks.

The Hitchhiker's Guide to Python, by Kenneth Reitz and Tanya Schlusser, turns these values into habits. Follow PEP 8, the community style guide, and the Zen of Python, which values explicit code and readability. Avoid classic traps such as mutable default arguments and late-binding closures, structure projects so people can navigate them, and add tests, documentation, logging and a license as if other people will use your code, because sooner or later they will. Its most distinctive idea is that you get better by reading well-made open-source projects such as Requests and Flask, the way writers read good writing.

They differ in emphasis. Van Rossum's case for indentation centers on the reader and the learner, while Lattner's centers on correctness and consistency. On types, van Rossum keeps Python's hints outside the runtime, partly to protect existing dynamic code; Lattner sees hints that the interpreter ignores and competing tools read differently as a limitation, and Mojo enforces declared types. Van Rossum put simplicity first and added speed decades later; Lattner starts from Python's slowness as its main weakness. The Hitchhiker's Guide is a 2016 snapshot, and some of its tool recommendations have aged.

What to do with it: before calling code finished, ask whether another programmer, or you later on, could debug and improve it. Indent consistently, name things for the reader, follow PEP 8, add types where the codebase is large or shared while leaving prototypes free, keep things simple until performance demands otherwise, read good code on purpose, and learn by building something you actually want to make.