XVI. Best Practices and Coding Conventions

Beautiful is better than ugly.

Tim Peters, Zen of Python

Introduction

When you start programming, the biggest hurdle seems to be writing code correctly so that computers can understand it. However, this hurdle is usually overcome quickly. As programs grow larger, it becomes clear that one of the biggest challenges is writing code that people can understand. We need to understand our code when we revisit it later, and ideally, others should understand it as well. Writing clean, maintainable, and bug-free code ensures that your work is accessible to others, fostering collaboration and future development. At its best, code can be elegant and aesthetic.

Consistent Naming Conventions

Using clear and consistent naming conventions helps make code more readable and understandable. Descriptive names for variables, functions, and classes enhance code clarity, making it easier for others to follow and maintain.


# Good naming example
class Book:
    def __init__(self, title, author, isbn):
        self.title = title
        self.author = author
        self.isbn = isbn

# Bad naming example
class b:
    def __init__(self, t, a, i):
        self.t = t
        self.a = a
        self.i = i

Code Formatting and PEP 8

Following PEP 8, Python's style guide, ensures that your code is formatted consistently. Consistent formatting makes your code look clean and professional, improving readability and reducing errors.


# PEP 8 compliant code
class Book:
    def __init__(self, title, author, isbn):
        self.title = title
        self.author = author
        self.isbn = isbn

# Non-compliant code
class book: def __init__(self, title,author,isbn): self.title=title;self.author=author;self.isbn=isbn

Writing Docstrings

Providing docstrings for functions, methods, and classes helps generate documentation and makes the code easier to understand. Docstrings describe the purpose and usage of a component, enhancing the readability and maintainability of the code.


class Book:
    """
    A class representing a book in a bookstore.

    Attributes:
        title (str): The title of the book.
        author (str): The author of the book.
        isbn (str): The ISBN number of the book.
    """
    def __init__(self, title, author, isbn):
        """
        The constructor for the Book class.

        Parameters:
            title (str): The title of the book.
            author (str): The author of the book.
            isbn (str): The ISBN number of the book.
        """
        self.title = title
        self.author = author
        self.isbn = isbn

Avoiding Global Variables

Minimizing the use of global variables helps maintain state consistency and reduces debugging complexity. By keeping variables scoped to where they are needed, you avoid unintended side effects and improve code clarity.


# Bad practice: Using a global variable
inventory = []

class BookStore:
    def add_book(self, book):
        global inventory
        inventory.append(book)

# Good practice: Avoiding global variables
class BookStore:
    def __init__(self):
        self.inventory = []

    def add_book(self, book):
        self.inventory.append(book)

Using Version Control Systems

Using a version control system like Git to track changes and collaborate with others is essential for any serious coding project. Version control systems help manage changes, maintain a history of revisions, and facilitate teamwork, ensuring that your project evolves smoothly and efficiently.