Style

This page records notes about coding style for consistency in the project—preferences, and reasoning behind choices.

String Interpolation

While Python provides several ways to interpolate strings (%-formatting, the str.format() method, template strings, f-strings), using a mixture of these is not conducive to making a codebase user friendly. An ongoing project is to be more consistent in the method used within pyani.

Generally, this means instances of other string interpolation types are being replaced with f-strings. The one exception to this is strings that occur within logging statements. In these cases, and in these cases only, f-string syntax is not to be used, in favour of the loggin library's version of the %-formatting syntax:

logger.debug("Connecting to database %s", args.dbpath)

The reason for this exception is that f-strings are evaluated early in the process of running the code, whereas the logging % syntax defers this to runtime, and only evaluates the statements that are triggered. This saves a lot of unnecessary evaluation.

Errors

When I started writing pyani, I didn't think much about error reporting. After a while I've developed some views on what works well and what doesn't. They're up for discussion, obviously…

• As a rule of thumb, scripts should report errors/warnings through a logger; 'backend' code should raise errors instead - where we currently pass a logger into the backend code, that's legacy poor coding on my part.