Tools II: Code Formatters

Overview

Teaching: 5 min
Exercises: 5 min

Questions

• How to format code with no effort on the part of the coder?

Objectives

• Know how to install and use a code formatter

Why does formatting matter?

• Code is read more often than written
• It’s a menial task that adds cognitive load
• Ensures all code in a project is consistent, even if contributed by multiple authors
• Setting up a formatter in your editor takes 5 minutes
• Those 5 minutes are redeemed across the lifetime of the project

Rules to choose a code formatter

1. Choose one
2. Stick with it

We chose black because it has very few options with which to fiddle.

Formatting example (5 min)

Using Visual Studio Code:

1. Open the file messy.py. Its contents should match:

   x = {  'a':37,'b':42,
   'c':927}
   y = 'hello '+       'world'
   class foo  (     object  ):
     def f    (self   ):
          z =3
          return       y **2
      def g(self, x,
          y=42
          ):
         # pylint: disable=missing-docstring
         return x--y
   def f  (   a ) :
      return      37+-a[42-a :  y*3]  # noqa: E203
   

2. Ensure that you have activated your “course” conda environment (see previous episode)
3. Make a trivial change to the file and save it: it should be reformatted automagically.
4. Use the undo function of VS Code to return the code to its unformatted state. Before saving again delete a ‘:’ somewhere. When saving, the code will likely not format. It is syntactically invalid. The formatter cannot make sense of the code and thus can’t format it.

Solution

After saving, the code should be automatically formatted to:

x = {"a": 37, "b": 42, "c": 927}
y = "hello " + "world"


class foo(object):
    def f(self):
        z = 3
        return y ** 2

    def g(self, x, y = 42):
        # pylint: disable=missing-docstring
        return x - -y


def f(a):
    return 37 + -a[42 - a : y * 3]  # noqa: E203

Ah! much better!

Still, the sharp-eyed user will notice at least one issue with this code. Formatting code does not make it less buggy!

Key Points

• Code formatting means how the code is typeset

• It influences how easily the code is read

• It has no impact on how the code runs

• Almost all editors and IDEs have some means to set up an automatic formatter

• 5 minutes to set up the formatter is redeemed across the time of the project i.e. the cost is close to nothing