Publishing companies establish formats for all the writing they produce. Editors and writers have to be familiar with the company’s style sheet and conform to the rules established in that manual. This ensures consistency across all publications, regardless of the writer. Following the style sheet should be second nature for writing professionals, much like consistent formatting is necessary in data science.
Python code formatting is just as important to coders as a grammatical style sheet is to an editor. Al Sweigart explored the importance of a code style sheet in his new book Beyond the Basic Stuff With Python: Best Practices for Writing Clean Code, published by No Starch Press.
What is code formatting?
Python code formatting comes down to building a set of rules for coders to follow that makes your code readable.
“Code is read more often than it’s written,” Sweigart said. “No one wants to read a novel that is contained entirely in one paragraph.”
A computer doesn’t care about how your code is formatted, but there are many reasons another human might need to read your code. Your code should certainly be understandable for when you or someone else reviews it.
“When you review your own code after you’ve written it, say to fix bugs or add features, readability helps you sort through to find exactly what you need to change or update,” Sweigart said.
Programming is a collaborative skill, and your coworkers may have to look over your work. Having a Python code formatting style guide to follow can help beginners on the team learn to code better and cut down on fights between coworkers during collaborative projects. With an established style across the board, the team will spend less time reformatting based on personal choices.
How to build a style sheet
The first place many coders start is with Python Enhancement Proposal #8 (PEP 8). Sweigart said it’s good to use this as a guide, but changes specific to the project or company must be made.
“Use what works for yourself or your team and discard the rest,” he said.
While there’s nothing specific that must be included in your Python code formatting style guide, just having one is a good start. Since style is so subjective, a team of developers is likely to produce inconsistent code writing because of each individual’s personal preferences.
“I think this is a case where simply having a code style for a group of software developers to stick to is better than having none,” Sweigart said.
One of the main things Sweigart dove into in his book was spacing. Empty space is an important part of readability, he said. For example, since spacing helps with readability, consider including horizontal and vertical spacing guidelines for coders to follow. Just like paragraph and chapter breaks make books easier to read, spacing can aid your code’s readability.
Code formatting tools
A style sheet is helpful for your Python code formatting, but an auto-formatting tool can also help. The most popular one for Python is Black.
Black’s name comes from a famous Henry Ford quote where he said the Model T was available in any color people wanted, as long as that color was black. The tool formats code automatically. If you don’t want to bother with a formatting style sheet, Black can do the heavy lifting for you.
“The main advantage of Black is that it’s made several decisions that most programmers can live with, and by adopting Black your team can save a lot of time bickering about what should go into a style guide,” Sweigart said.
Similar to Ford’s car color options, Black doesn’t offer too much flexibility in its style choices. Some settings can be changed, but Sweigart said one of the tool’s strengths is the inflexibility: The auto-formatting tool helps keep style consistent without wasting time.
“Making sure every line of code is adhering to the chosen style guide is tedious work that should be done by fast computers rather than expensive software engineers,” he said.
Why code formatting matters
The main benefit to Python code formatting and investing time in developing style guides is that it makes the content easy to understand. Many beginners learn Python by reading the code, so even if the computer doesn’t need consistency and readability to process it, good formatting can help other humans improve their skills.
“Programming is hard enough; you want reading and parsing the code to be as easy as possible,” Sweigart said.
Check out Chapter 3 from Sweigart’s new book Beyond the Basic Stuff With Python, published by No Starch Press, to learn more about Python code formatting.