10.1 Importance of good programming practices
Good programming practices are important because they:
- Improve code readability and maintainability.
- Facilitate debugging and troubleshooting.
- Promote code reusability.
- Enable effective team collaboration.
- Maintain overall code quality.
For the purpose of this course, we should be able to use the following good programming practices.
10.1a Inline comments
In Python, inline comments are comments that appear on the same line as the code and are used to provide brief explanations or clarifications about that specific line of code. Inline comments start with the # symbol and continue until the end of the line.
Example 10.1.1 - Example with various inline comments
result = 5 # Assigning the value 5 to the variable result
final_result = result * 2 # Multiplying result by 2 to get the final result
# Printing the final result
print(final_result)
10.1b Python block comments
Block comments in Python are used to provide explanations or descriptions for a section of code, rather than a single line. They help in documenting what the code does and why certain decisions were made. Block comments are particularly useful for complex sections of code or for providing overall context.
Example 10.1.2 - Using block comments in Python
# This function calculates the area of a rectangle.
# It takes two parameters:
# - width: The width of the rectangle.
# - height: The height of the rectangle.
# The function returns the area by multiplying
# the width and height.
def calculate_rectangle_area(width, height):
return width * height
10.1c Multi-line strings or docstrings
Use triple quotes (''' or """) for docstrings, which provide documentation for modules, classes, and functions, and can be accessed programmatically.
Sometimes the triple quotes are used for block comments but that it is not a good practice and one should use # for regular comments, including block comments, as they are intended to be brief explanations for developers and are ignored by the interpreter. Whereas triple quotes, are used to write docstrings, which are a special kind of comment meant to describe modules, functions, classes, or methods.
Example 10.1.3 - Multi-line strings or docstrings.
def calculate_rectangle_area(width, height):
"""
Calculate the area of a rectangle.
Parameters:
width (int, float): The width of the rectangle.
height (int, float): The height of the rectangle.
Returns:
int, float: The area of the rectangle.
"""
return width * height
10.1d Code indentation
Python code indentation refers to the practice of structuring code blocks by using spaces or tabs to visually indicate the level of nesting within the code. In Python, indentation is not just for readability but it is a fundamental part of the language's syntax and determines the structure of the code.
Example 10.1.4 - Example of Python code indentation
if condition:
print("This statement is inside the if block")
if nested_condition:
print("This statement is inside the nested if block")
else:
print("This statement is inside the else block of the outer if")
else:
print("This statement is inside the else block")
10.1e Meaningful variable names
Meaningful variable names can help with:
-
Readability - Meaningful variable names make the code easier to read and understand.
-
Maintainability - Code with clear and descriptive variable names is easier to maintain.
-
Debugging - Descriptive variable names can make it easier to identify where something might be going wrong in the code.
-
Documentation - Self-explanatory variable names reduce the need for excessive comments. Good variable names can act as documentation, explaining the purpose of the variable directly in the code.
Example 10.1.5 - Example with non-meaningful variable names
In the above example, it is unclear what x, y, and z represent, making the code harder to understand.
Example 10.1.6 - Example with meaningful variable names
In the above example, the variable names clearly describe what they represent, making the code more readable and understandable.