Skip to content

🔵 Read and Understand the Project

Study the working example.

WHY?

Professional work often requires understanding existing code rather than starting from nothing.

Reading a working example helps explain the problem, data, project structure, execution flow, and results.

Focus on the overall flow and objective of the project. It's not necessary to understand every line of code at this point.

Professional Project Organization

Real-world projects contain many files, so most professional projects follow a predictable organization. You can use the Professional Python Project Explainer to get information about common files and folders.

Objectives

By the end of this step you should understand:

  • the purpose of the project
  • the main tools and techniques used
  • how data flows through the program

1. Start with the Supporting Information

Look at the project on GitHub.

README.md (root project folder)

Scroll down to read the README.md. This is the key landing page for GitHub projects. It should include:

  • What is the purpose of the project?
  • What problem does it address?
  • What are the instructions for running it?

GitHub About Section

Try to find the "About" Section. It should include:

  • A short project description
  • There might be a clickable link to the project documentation.
  • Topics (keywords) that describe the project

Project Documentation

  • Click the documentation or website link in the GitHub About section, if provided.
  • Read the documentation home page (usually docs/index.md).
  • Explore a few other documentation pages.
  • Notice how the project explains its purpose, provides instructions, and presents its work to others.
  • GitHub hosts the project documents via GitHub Pages.

GitHub Activity

  • Find the Commits link on the Code page.
  • How many commits have been made?
  • When was the most recent commit?
  • Can you trace the evolution from the messages?
  • Explore the Actions tab.
  • Are automated checks passing?

Commits record changes to a project. Try clicking on one to see what changed.

2. Then Look at the Project Organization

Many projects are organized using common folders.

Documentation (docs/)

First, find the docs folder. This holds the information explored above when reviewing the project documentation. The files have a .md extension and are written in Markdown, a super simple markup language. GitHub Pages hosts them as web pages for easy reading and navigation.

Then, explore in more detail. We'll start by scanning the project configuration information and then start looking into the project code (the instructions).

Data (data/)

Data is typically stored in a folder named "data". Explore any available input datasets.

  • What does one row or record represent (the grain)?
  • What are the important variables?
  • How is data used in the program?

Source Code (src/)

Python modules are typically stored in a folder named src (short for "source code"). There may be another package folder under src. Keep going until you find Python files (with a .py extension).

More about source code

Execution often begins in the main() entry point towards the end of the file:

def main():
    # This is where execution logic begins

When exploring the example project:

  • identify the command and file that starts execution (see README.md).
  • find the main() function or application entry point (e.g. in src/).
  • observe which functions are called by the main() function.
  • identify any reusable utility modules (supporting .py files) and their functions
  • follow how data moves through the program
  • note what arguments are passed to functions (inside parentheses) and what each function returns
  • find the functions - they are reusable blocks of instructions and usually have a descriptive name

Tests (tests/, if present)

Many projects will have a tests folder. We can test our functions to ensure they are still working correctly after making changes to the project. Tests can be run automatically and are a common part of working with code.

  • Does the project include a tests folder?
  • If so, how many modules (Python files) are there?
  • What are they named?
  • Open a test file (if available) - what src files are imported?

Outputs (artifacts/ or output/)

If there is an artifacts or output folder, it typically holds outputs generated by the project. These will often be empty until you run the project code to generate them.

  • Review any available generated results, charts, or reports

Notebooks (notebooks/)

Some projects might include a Jupyter notebook in the notebooks folder.

If there is a file in the notebooks folder, it might have a .ipynb file extension. Click on it and read the notebook. Try to follow the logic.

Project Configuration (pyproject.toml)

The pyproject.toml is in the root project folder. It configures a Python project. It might look a bit overwhelming, but it will stay mostly the same for all projects. Just scan it and see if you can:

  • Identify the required Python version.
  • Review the external dependencies (free packages of code) used by the project.
  • Distinguish runtime dependencies from development tools.

Marimo Reactive App (app.py, if present)

Marimo supports interactive, reactive Python notebooks and apps. Some Marimo apps are published online along with project documentation. Look for a Python file such as app.py. It may be in the project root, src/, or notebooks/. Marimo reactive apps are new - not all example projects have them.

Success

You are ready to continue when you can:

  • [ ] Explain the problem and intended results.
  • [ ] Describe any data, its grain, and important variables.
  • [ ] Identify the Python version, dependencies, and project structure.
  • [ ] Locate the project code.
  • [ ] Identify which file includes the main execution entry point.
  • [ ] Identify any supporting utility modules.
  • [ ] Identify any Jupyter notebooks (usually in the notebooks folder)
  • [ ] Identify any reactive Marimo notebooks (may be named app.py)

◄ Back to 🔵 Workflow B