Coding Methodology in Python

Acknowledgement: This post is based mainly on Dr. Thai Ha Nguyen’s presentation and slides and partly on on TA, STA, and peers’ responses from the course AIO2025 offered by AI VIETNAM.

Relevance: The audience of this lecture were those who have learned Python for AI 102, had some coding experience, and known a bit of AI knowledge. Absolute beginners are encouraged to read the material and repeatedly practice coding without AI assistance to strengthen their coding and code-reading skills.

Be always intentional when writing and managing code. Learn logics. Don’t overuse AI assistant when starting.
-Dr. Thai Ha Nguyen

In today’s post, we’ll explore clean code principles for Python and standard project structures. We’ll mainly mention common concepts without particular examples. Details may be updated in the future.

Roadmap for learning Data Science

Learners should follow the core process of managing a Machine Learning projects.

1. Planning
2. Proof of Concept (PoC)
3. Implementation
4. Deployment

Learners can work on some practical projects:

1. Sales Forecasting and Demand Prediction and Applied XAI
2. Inventory Optimization Tools
3. Customer Segmentation for Marketing Strategy using Unsupervised Learning.

Introduction to Clean Code and PEP-8

Our goal of this section is to comprehend and be able to apply clean code principles and PEP-8 so that our source code is readable, efficient, and maintainable.

Writing code is like building a house. A house can still be completed by putting things together but it’s likely not to last long without a blueprint. The same goes for code: without a clear architecture, solid logic, and clean design, it’s prone to errors, hard to understand, and difficult to maintain.

Anything that can go wrong will go wrong.
Edsel Murphey’s Law

Clean Code

The core principles of clean code are:

1. Readable: “future” we and others should easily understand its purpose and how it works.
2. Maintainable: code should be easy to be modifed, extended, and reused without making errors.
3. Testable: code should be easy to write and automate unit tests.
4. Extensible: code should be easy to add new features without changing existing code.

You may wonder, How important is clean code in practice?

When working on a project with colleagues, like in a company, we must read each other’s code which can be thousands of lines. This is when clean code comes in useful. Clean code is not only favored in theory but a key factor to boost work efficiency and improve team collaboration, and lower long-term maintenance cost. To be specific:

• Minimize bugs: clean code helps identify and prevent potential errors and lower debug and repair time.
• Improve team work: clean code helps team members understand and work with each other’s code easily.
• Save time lone-term: clean code may take time and effort to build in the first place but will save time during maintenance and development. This is to avoid technical debt.
• Extend easily: clean code makes it esy to add new features without modification.

Some examples for clean code are:

• good format: space out for code to be clear
• meaningful names: variables, functions, and classes should have names meaningful to the program.

Nevertheless, there are situations where we don’t have to clean code:

• Short-live/Emergency scripts: when the system encounters a serious accident, we need to handle the situation first, and refactor afterwards.
• Exploratory code: clean code is unnecessay when learning a concept.
• Sample code: we can skip clean code when checking some idea in a short time and can always refactor if implementing the idea.
• Only-current-you code: Only current-you need it!

PEP-8

PEP-8 is short for Python Enhancement Proposal 8 introduced by Guido van Rossum—Python’s inventor. It is the official format for Python code, helps preserving code unity and eligibility for projects.

Naming Convention

Indentation and Whitespace

Standard Code Line

Standard Import
We should import libraries and modules in different blocks based on their origin. Commonly, there are three blocks in the following order:

1. Python libraries: os, sys, math
2. Third-party packages: requests, numpy, pandas
3. Internal modules: from myproject.models import User.

Line Break and Class/Function Structure

Documentation: Docstring and Annotation Basics

Checking Tools

flake8: check for redundancy black . : format all black file_name: format file_name pyplint: analyze more than black and grade our code mypy: check error

Standard Structure for Projects

Similar to writing Python code, it’s essential to organize a Python project in order to build a healthy development cycle. There may be a few ways to construct a standard repository structure. Below is one of them. Using files described in the root directory ensures a project is efficiently managed and straightforward for contributors and readers.

1. Root directory project_name/
   • README.md: outlines a project’s goal, setup instructions, usage examples, and contributions
   • requirements.txt: lists project dependencies
   • setup.py: defines and installs packages
   • pyproject.toml (preferred): specifies build íntructions, project dependencies, and project metadata (license, author, descriptions, etc)
   • .gitignore: contains files and folders Git should ignore/track such as temporary files, log files, or personalfiles.
2. Source code project_name/src/
   • Main modules
   • Main packages
3. Tests project_name/tests/
   • unittest
   • pytest
4. Documentation project_name/docs
   • API
   • Usage
5. Resources project_name/resources/
   • Static resources
   • Templates
   • Assets

It’s adequate and fast to build our repository structure using Command-Line Interface generator (CLIgen) such as Cookiecutter Data Science.

Pythonic Style

Our goal of this section is to familiarize ourselves with standard Python programming and utilize its unique features efficiently.

There are 19 guiding principles for Python written by Tim Peters in PEP 20. You can check them out with import this.

We apply Pythonic style to utilize unique features and characteristics of Python. It not only preserves clean code and PEP-8 but adheres to Python’s philosophy. Let’s take a look at some Pythonic cases.

1. Use list, dict, and set comprehensions to create a sequence.
   • All on one line makes it faster to create.
   • It’s very readable one you’re familiar with the syntax.

     dict_comprehension = {i: i * i for i in range(7)}
     

2. Context manager with statement to open and close a file automatically.
   • with prevents memory leak, releases resources correctly, and is safer for exception handling.
   • It’s commonly used for file management, network database, lock thread, benchmark, transaction database, and so on.

     with open("file_name.txt", "r") as file:
      content = file.read()
     

3. @contextmanager is a decorator.
   • @contextmanager comes from contextlib.
   • It temporarily changes the system configuration and recovers once done.
   • It measures operation time.
   • It manages network database, Redis, or API.
   • It creates a temporaty environment for testing.

     from contextlib import contextmanager
     @contextmanager
     def file_reader(filename):
      f = open(filename, "r")
      try:
       # perform with statement
       yield f
      finally:
       # clean up everything and close the file
       f.close()
     # use context manager
     with file_reader("file_name.txt") as file:
      print(file.read())
     

4. @property is a decorator, making a method become an attribute.
   • No need parentheses () in the end if there is no argument.
5. Comparison and condition:

class Weird:
    def __eq__(self, other):
        # it equals anything
        return True

w = weird()
print(w is None)

'''
False   
'''

class Weird:
    def __eq__(self, other):
        # it equals anything
        return True

w = weird()
print(w == None)

'''
True
'''

valid = True
if valid:
    print("True")

valid = True
if valid == True:
    print("True")

items = []
if not items:
    print("Empty")

items = []
if len(items) == 0:
    print("Empty")

a_list = [1, 2, 3]
item = 4
if item in a_list:
    print(f'{item} is in a_list')

a_list = [1, 2, 3]
item = 4
for i in a_list:
    if i == item:
        print(f'{item} is in a_list')
        break

value = 7
if 0 < value < 8:
    print(f'{value} is in range')

value = 7
if value > 0 and value < 8:
    print(f'{value} is in range')

Principles for Writing Neat Code

Our goal of this section is to understand various rules and designs to build high-quality code.

As mentioned logging can be used to catch bugs in the program. The purposes of using logging and print may be mistaken for each other. logging is a feature to journal code professionally with different levels while print is to catch errors quickly but have its own drawbacks.

SOLID Rule and Design Patterns (Advanced) - to be updated

Our goal of this section is to learn how to organize projects, divide into modules, and write highly extensible code.

Single Responsibility

Open/Closed

Liskov Substitution

Interface Segregation

Dependency Inversion

4

Pro tip: Use AI to create problems, with hint docstrings, and test cases. Export it to colab files and start practicing. Once you’ve done, ask AI to analyze your solutions and provide answer keys and learned lessons. You can use lecture slides as an attachment to your question.

A sample prompt: “Create twenty Python programming problems from easy to diffcult. They should adhere to the lesson content in slides attached. They should have hint docstrings and test cases for each problem and learners need to complete them. After that, provide solutions separately and give lessons learned from each problem.”

https://colab.research.google.com/drive/1hwdu33Mo1wxoOcNWV80qSy2YWVodtyeL?usp=sharing

FAQ

Here are some good questions asked during class. The answers to these questions came from either some admin, TA, STA, or members of AIO2025.