Author

Subarna Saha and Shabrina Akter Shahana

Set Up PEP 8 Compliance

One can ensure that the Python code adheres to PEP 8 guidelines for readability and consistency by using flake8.

1. Install flake8 (or another linter):

   pip install flake8
   

2. Check if this project follows pep-8 guidelines:

   flake8 .
   

Description of the Coding Convention

In software development, adhering to coding standards is essential for maintaining readability and consistency across projects. This document outlines our implementation of the PEP 8 coding convention, which serves as a widely accepted guideline for writing Python code. While we have adopted the core principles of PEP 8, we have also made certain customizations to better align with our specific project needs and coding style. The following sections will detail these adjustments ensuring clarity and coherence in our codebase.

1. Indentation

• Use 4 spaces per indentation level.
• No tabs; always use spaces. (Most editors can convert tabs to spaces automatically.)

def example():
    if True:
        print("Use 4 spaces per indentation level.")

2. Maximum Line Length

• Limit all lines to a maximum of 120 characters.
• For comments and docstrings, limit to 170 characters.

You can split long lines using parentheses or backslashes:

my_variable = (some_value + another_value +
               yet_another_value)

3. Blank Lines

• Surround top-level function and class definitions with two blank lines.
• Method definitions inside a class are separated by a single blank line.

class MyClass:
    
    def method_one(self):
        pass
    
    def method_two(self):
        pass

4. Imports

• Imports should usually be on separate lines.

import os
import sys

Imports should be grouped in the following order:

1. Standard library imports
2. Related third-party imports
3. Local application/library-specific imports

Use absolute imports whenever possible.

from mymodule import myclass

5. Whitespace in Expressions and Statements

• Avoid unnecessary whitespace in expressions:

# Correct:
a = f(x) + g(y)

# Incorrect:
a = f( x ) + g( y )

• Do not use extra spaces around operators when used in a function call:

# Correct:
foo = (a + b) * (c - d)

# Incorrect:
foo = ( a+b )*( c-d )

• Use single space around both sides of binary operators (e.g., =, +, -, *, /, etc.):

# Correct:
x = 1
y = x + 2

# Incorrect:
x=1
y = x+ 2

6. Naming Conventions

• The app names in the project should be content-based: users, appointments.
• The folder names in the views and static folders should be role-based: doctors, patients.
• File and folder names should use lowercase with underscores: prime_checker.
• Variables, functions, and methods should use lowercase with underscores: my_function().
• Class names should use PascalCase: MyClass.
• Constants should be written in all uppercase with underscores: MAX_VALUE.
• URL routes and names should use lowercase with hyphens: lab-techinician-dashboard.
• In each file, code should be enclosed within specific boundaries, such as Doctor part start and Doctor part end. These boundaries should be role-based.

# Doctor part start
  # Write the code necessary for the functionalities required by the Doctor role
# Doctor part end

# Patient part start
  # Write the code necessary for the functionalities required by the Patient role
# Patient part end

• Avoid using single-character names except for counters or iterators (e.g., i, n).
• magic objects or attributes that live in user-controlled namespaces use both starting and trailing double underscores (e.g., init, import or file). They should be used only as documented.

7. Access Modifiers

There are no specific conventions for access modifiers in PEP-8. Access modifiers in Python are based on naming conventions, not explicit keywords. Here's the general convention:

• Public: Don't use any leading underscores (e.g., my_variable).
• Protected: Use a leading underscore (e.g., _my_variable).
• Private: Use double leading underscore (e.g., __my_variable).

8. Blank Lines

• Top-level function and class definitions should be surrounded by two blank lines.
• Method definitions inside a class should be separated by a single blank line.
• Additional blank lines should be used to separate logical sections of code, comments, or docstrings for clarity.

9. Comments

• Use comments to explain why, not what.
• Block comments should start with a # and a single space. Place them above the code block they refer to.
• Inline comments should be separated by at least two spaces from the statement and start with a # and a single space:

x = x + 1  # Increment x by 1

10. Docstrings

• Use docstrings to describe the purpose of a function or class.
• The docstring should start and end with triple quotes (""") and be in the following format:

def my_function():
    """
    Briefly describe what the function does.
    
    :param param1: description of param1
    :return: description of return value
    """
    pass

11. Avoid Trailing Whitespace

• No trailing whitespace at the end of lines or blank lines with spaces.

12. Function and Variable Annotations

• Use function annotations to describe the expected types of function arguments and return values:

def my_function(arg1: int, arg2: str) -> None:
    pass

Advantages of PEP 8 Coding Convention

• Improves Readability: PEP 8 enforces a consistent style that makes code easier to read and understand, both for the original author and for others who may read or maintain the code later.

• Facilitates Collaboration: By adhering to a common style guide, team members can work together more effectively, as the code follows a uniform format, reducing the time needed to understand each other's code.

• Enhances Maintainability: Consistent code style helps in identifying issues more quickly and makes it easier to modify or extend code in the future, reducing the likelihood of introducing bugs.

• Promotes Best Practices: PEP 8 encourages writing code in a way that adheres to best practices in Python development, leading to higher-quality and more professional code.

Disadvantages of PEP 8 Coding Convention

• May Impose Constraints: Strict adherence to PEP 8 might impose constraints that could be restrictive in some cases, potentially limiting certain coding styles or practices that might be more suitable for specific scenarios.

• Learning Curve: New developers or those unfamiliar with PEP 8 might face a learning curve in understanding and applying the conventions, which could slow down initial development.

• Overemphasis on Style: Focusing heavily on following PEP 8 might sometimes lead to an overemphasis on code style rather than on actual functionality, potentially diverting attention from more critical aspects of development.

• Increased Overhead for Small Projects: For very small projects or scripts, the overhead of strictly following PEP 8 conventions might seem excessive compared to the benefits, especially if the project is not intended for long-term maintenance.

References

Following can be used to learn more about the coding convention:

• PEP 8 document
• Datacamp PEP-8 tutorial