Clean Code: Definition and Principles - Part 2

Clean code refers to well-organized, easily understandable, and maintainable code. Now, let's delve into part 2 of specific principles that guide clean code writing:

Naming Conventions (D)

1. Use clear and non-confusing naming conventions.
2. Create meaningful distinctions with naming conventions. (Crucial for abstraction)
3. Find easily pronounceable naming conventions.
4. Choose names that can be easily found and accessed when needed.
5. Avoid hidden numbers and constants within the code.
6. Avoid adding a set of starting tags to encoding and variables.

# Clear and non-confusing naming conventions
customer_list = []  # Good
data = []          # Bad - unclear

# Meaningful distinctions with naming conventions
class Shape:
    def calculate_area(self):
        pass

class Circle(Shape):  # Good - clear distinction
    def calculate_area(self):
        pass

class Rectangle(Shape):  # Good - clear distinction
    def calculate_area(self):
        pass

# Easily pronounceable naming conventions
user_preferences = {}  # Good
usr_prefs = {}         # Bad - not easily pronounceable

# Easily found and accessed names
PI = 3.14  # Bad - not easily found, lacks context
PI_VALUE = 3.14  # Good - easily found and accessed

# Avoid hidden numbers and constants
discount_multiplier = 0.9  # Good - clear purpose
total_price = product_price * discount_multiplier  # Good

# Avoid starting tags to encoding and variables
encoded_data = encode(data)  # Good
d_encoded = encode(data)     # Bad - unclear

Function Guidelines (E)

1. Keep it small.
2. Should do one thing and do it well.
3. Have a clear and descriptive name.
4. Take as few arguments as possible.
5. Should not contain side effects.
6. Do not pass flag (true/false) arguments into the parameters and make different method calls within this method.

# Keep it small
def calculate_total_price(product_price, quantity):
    # Small function that calculates the total price
    return product_price * quantity

# Do one thing and do it well
def send_email(to, subject, body):
    # Sends an email
    pass

# Have a clear and descriptive name
def get_user_data(user_id):
    # Retrieves user data
    pass

# Take as few arguments as possible
def calculate_area(radius):
    # Calculates the area of a circle
    pass

# Should not contain side effects
def update_user_profile(user_id, new_data):
    # Updates user profile - side effect as it modifies external state
    pass

# Do not pass flag arguments into parameters and make different method calls
def process_data(data, normalize=False):
    if normalize:
        normalize_data(data)
    else:
        process_raw_data(data)

Commenting Rules (F)

1. Strive to express yourself within the code.
2. Avoid unnecessary comments.
3. Do not add comment lines to separate the start and end of the code.
4. Do not turn the code into a comment. 
5. Delete unnecessary code.
6. Explain the reason for writing a comment.
7. Use comments as code explanations.
8. Use comments as warnings for outcomes.

# Strive to express yourself within the code
result = calculate_area(radius)  # Good - self-explanatory

# Avoid unnecessary comments
# This is a loop that iterates over each element
for element in elements:  # Bad - unnecessary comment
    process_element(element)

# Do not add comment lines to separate the start and end of the code
# ===============================
# Function to calculate area
# ===============================
def calculate_area(radius):
    return 3.14 * radius ** 2

# Bad - unnecessary comments for separation

# Do not turn the code into a comment. Delete unnecessary code
# unused_variable = 42
# Commented out because it's not needed anymore
# Better to remove the code entirely

# Explain the reason for writing a comment
# Using a specific algorithm due to performance requirements
# This comment explains the reason for choosing a particular approach

# Use comments as code explanations
# This loop calculates the sum of all elements
for element in elements:
    total += element

# Use comments as warnings for outcomes
# Warning: Changing this code may affect the entire system.
# This comment alerts developers about potential consequences.

These examples demonstrate how a professional programmer might apply each Clean Code principle in Python. The emphasis is on clarity, readability, and maintaining a codebase that is easy to understand and work with.

If you need further information or have specific questions, feel free to ask! Tahsin Soyak [e-mail]