Writing clean, maintainable code is an art and a science---it is a challenging skill that is difficult to learn except through experience. We have collected a number of coding examples that demonstrate good coding practices.
Functions (and classes) that are used by several modules should be placed in a separate module, typically called a "utility" module. Sometimes, even when a function is only used in a single location, it should still be extracted into a utility module. In this case study, we consider when it makes sense to split out single-use functions into a utility module and when it should be left near its invocation.
It is easy, when fixing software bugs, to make the smallest possible fix to get some code working. However, unless there are severe time constraints, it is important to understand the context in which the code occurs, and to view the bug fix as a chance to clean up the code. This case is an example of a "quick fix" that could have been a nice chance to clean up the code.
A context manager was used for file loading but included code that was unrelated. At some later point a developer deleted more code than he intended.
Naming is one of the most important parts of writing clean code. Vague variable names are not helpful. Inaccurate variable names are misleading! As a codebase evolves, variable names that were once appropriate can become stale and subtly inaccurate. Good coders will update variable names to keep them precise and correct as the codebase evolves. Updating the names frequently can be a headache, especially if the "name" is used in several different entities through out a codebase. Try and make names as "future proof" as possible. To do this, try and consider how the code might evolve in the future, and see if you can think of a variable name that will continue to be precise even as the codebase changes. Of course don't ever sacrifice precision or clarity for the sake of future proofing!