"God is in the details" an assertion made by architect Ludwig Mies van de Rohe holds for code; as badly written code is a culmination of small details like; poor naming conventions, dependencies that are excess to requirements, classes and functions that do too much, duplicated code.

For variables, these naming conventions, while not set in stone, can help improve code readability.

• Use intent-revealing names - a name that requires a comment is no intent-revealing name.

•   import datetime
  
    # Get current date
    ymdstr = datetime.date.today().strftime("%y-%m-%d") 
  
    current_date: str = datetime.date.today().strftime("%y-%m-%d")
  

• Make meaningful distinctions and avoid disinformation.

• Use searchable names.

•   import time
  
    #Bad
    # What is the number 86400 for again?
    time.sleep(86400)
  
    # Good
  
    SECONDS_IN_A_DAY = 60 * 60 * 24
    time.sleep(SECONDS_IN_A_DAY)
  

• Clarity over entertainment value - say what you mean.

• Add meaningful context - use prefixes to help readers understand when variables are part of a larger structure.

• Avoid unneeded context.

•   # Bad
    class Car:
        car_make: str
        car_model: str
        car_color: str
  
    # Good
    class Car:
        make: str
        model: str
        color: str
  

Functions are building blocks and should be small and then even smaller.

• Do only one thing and do it well, functions doing more than one thing leads to functions that are harder to test, compose, and reason about.

•   from typing import List
  
    # Bad
    class Client:
        active: bool
  
    def email(client: Client) -> None:
        pass
  
    def email_clients(clients: List[Client]) -> None:
        """Filter active clients and send them an email.
        """
        for client in clients:
            if client.active:
                email(client)
  
    # Good
  
    class Client:
        active: bool
  
    def email(client: Client) -> None:
        pass
  
    def get_active_clients(clients: List[Client]) -> List[Client]:
        """Filter active clients.
        """
        return [client for client in clients if client.active]
  
    def email_clients(clients: List[Client]) -> None:
        """Send an email to a given list of clients.
        """
        for client in get_active_clients(clients):
            email(client)
  

• Code should read like a top-down ltr narrative, one level of abstraction at a time. With more than one level of abstraction, the function is doing too much.

• Avoid side effects - A function produces a side effect if it does anything other than take a value in and return another value or values. For example, a side effect could be writing to a file or modifying some global variable. Now, you do need to have side effects in a program on occasion - for example, you might need to write to a file. In these cases, you should centralize and indicate where you are incorporating side effects. Don't have several functions and classes that write to a particular file - rather, have one (and only one) service that does it.

• Function arguments - the ideal number of arguments a function should have is 2 or less (dyadic to niladic). A large amount of parameters is usually a sign that a function is doing too much (has more than one responsibility). Try to decompose it into smaller functions having a reduced set of parameters, ideally less than three. From a testing standpoint, the more arguments, the more difficulty in writing tests for them.

Comments - a necessary evil and a testament to our inability to express ourselves properly. Create comments only in; necessary situations like explanation of intent, clarification, warning of consequence, To-do comments, and for amplification.

•   // Don't run unless you
    // have some time to kill.
    public void _testWithReallyBigFile()
    {
    writeLinesToFile(10000000);
    }
  

•   //TODO-MdM these are not needed
    // We expect this to go away when we do the checkout model
    protected VersionInfo makeVersion() throws Exception
    {
    return null;
    }
  

Single Responsibility Principle (SRP) - A class should have only one reason to change. The reasons here are the responsibilities managed by a class or function.

Don't Repeat Yourself(DRY) - Often you have duplicate code because you have two or more slightly different things, that share a lot in common, but their differences force you to have two or more separate functions that do much of the same things. Removing duplicate code means creating an abstraction that can handle this set of different things with just one function/module/class. Getting the abstraction right is critical. Bad abstractions can be worse than duplicate code, so be careful! Having said this, if you can make a good abstraction, do it! Don't repeat yourself, otherwise, you'll find yourself updating multiple places any time you want to change one thing.