Best Practices and Pitfalls in Declaring Default Values for Instance Variables in Python

Core Concepts of Default Value Declaration for Instance Variables in Python

In Python object-oriented programming, declaring default values for instance variables involves the fundamental distinction between class variables and instance variables. Class variables are declared directly in the class definition and belong to the class itself, whereas instance variables are bound via self in the __init__ method and are unique to each instance.

Behavioral Differences Between Class and Instance Variables

Consider the following two declaration styles:

class Foo:
    num = 1  # Class variable declaration

And

class Foo:
    def __init__(self):
        self.num = 1  # Instance variable declaration

Although both approaches allow the operation bar = Foo(); bar.num += 1, their underlying mechanisms are fundamentally different. The class variable num belongs to the Foo class itself and is shared across all instances at the same memory location, whereas the instance variable num is allocated independent memory for each instance upon creation.

Sharing Pitfalls with Mutable Defaults

When the default value is an immutable type (e.g., integers, strings), both declaration styles function similarly:

>>> class TestB():
...     def __init__(self, attr=1):
...         self.attr = attr
...     
>>> a = TestB()
>>> b = TestB()
>>> a.attr = 2
>>> a.attr
2
>>> b.attr
1

However, when the default value is a mutable type (e.g., lists, dictionaries), class variable declaration leads to unintended sharing behavior:

>>> class Test():
...     def __init__(self, attr=[]):
...         self.attr = attr
...     
>>> a = Test()
>>> b = Test()
>>> a.attr.append(1)
>>> a.attr
[1]
>>> b.attr
[1]

This phenomenon arises from the evaluation timing of Python function parameter defaults—default values are created once at function definition and shared across subsequent calls. For mutable types, this causes all instances' attr attributes to reference the same list object.

Pythonic Solutions

For mutable type defaults, it is recommended to use None as a placeholder and explicitly create a new object within the __init__ method:

>>> class TestC():
...     def __init__(self, attr=None):
...         if attr is None:
...             attr = []
...         self.attr = attr
...     
>>> a = TestC()
>>> b = TestC()
>>> a.attr.append(1)
>>> a.attr
[1]
>>> b.attr
[]

This approach ensures that each instance receives an independent object reference, preventing unintended data sharing. For immutable types, defaults can be set directly in the __init__ parameters:

class Foo:
    def __init__(self, num=1):
        self.num = num

Design Principles and Best Practices

From a software engineering perspective, declaring instance variables within the __init__ method offers several advantages:

First, it explicitly denotes the variable's instance scope, avoiding confusion that may arise from class variables. As noted in the reference article, some developers pre-declare class variables for IDE autocompletion:

class Person:
    name = None
    age = None
    
    def __init__(self, name, age):
        self.name = name
        self.age = age

While this practice addresses tooling support, it contravenes the Python philosophy of "Explicit is better than implicit." Class-level None declarations lack semantic value and may mislead code readers.

Second, __init__ centralizes instance initialization logic, enhancing code maintainability. When modifications to defaults or additions of new instance variables are needed, adjustments are confined to a single location.

Finally, this pattern aligns with practices in mainstream Python frameworks (e.g., Django), promoting code style consistency and team collaboration efficiency.

Advanced Application Scenarios

For scenarios requiring complex default value logic, consider employing the factory pattern or configuration objects:

class ConfigurableClass:
    DEFAULT_CONFIG = {"setting1": "default", "setting2": 100}
    
    def __init__(self, config=None):
        self.config = self.DEFAULT_CONFIG.copy()
        if config:
            self.config.update(config)

This method preserves the independence of defaults while offering flexible configuration override mechanisms.

Conclusion

Correctly declaring default values for Python instance variables requires a comprehensive consideration of variable scope, mutability semantics, and engineering practices. Setting instance variables via parameter defaults or None checks within the __init__ method is the most Pythonic approach. Particularly for mutable types, defensive programming strategies are essential to avoid object sharing and ensure the independence of each instance's state. These practices not only enhance code quality but also establish a solid foundation for future maintenance and extension.