Presenting Finished Programs — I can present a finished program with clear instructions and documented choices and trade-offs.

Writing code is only half the battle. From the earliest days of computing, programmers have struggled with a persistent problem: how do you make sure that someone else — or even your future self — can understand what a program does and why it was built that way? The practice of presenting finished programs with clear documentation evolved over decades as software projects grew from single-page scripts to systems containing millions of lines of code. Understanding this history helps explain why professional developers today spend nearly as much time on documentation as they do on writing code itself.

This history reveals a central question that applies to every project you build: If you hand your program to someone who has never seen it before, can they understand what it does, how to run it, and why you made the choices you did? That question is the focus of this entire lesson.

Presenting a finished program is more than pasting your code into a document. It requires thinking about your audience — someone who needs to run your code, understand your logic, and potentially modify it later. The following core principles form the foundation of effective program presentation.

The diagram below maps out the key components you should include when presenting a finished Python program. Think of it as a checklist: each box represents a section of your deliverable, and the arrows show the natural reading order for someone encountering your project for the first time.

Notice how the first five components are about communication rather than coding. A common mistake is to submit a program with no README and no comments, forcing the reader to reverse-engineer your intentions. That approach might work for a 10-line script, but it falls apart quickly for anything larger. By following this structure, you give your audience a guided tour of your project from the outside in — starting with the big picture and ending with the details.

The README File

A README (often written as README.md using Markdown) is the first file a reader sees in your project folder. It should answer three questions immediately: What does the program do? How do I run it? and Why was it built this way? Below is a template for each section you should include.

Section-by-Section Breakdown

Project Title & Purpose. Start with a one- or two-sentence summary. For example: "This program simulates a text-based adventure game where the player navigates a dungeon, collects items, and battles a final boss." Keep it concrete — avoid vague phrases like "This is my Python project."

Setup Instructions. List every step required to run the program. Include the Python version you used (e.g., Python 3.10), any third-party libraries (installed via pip install), and the exact command to run the program (e.g., python main.py). If your program reads from a file, mention where that file should be placed.

Usage Examples. Show a sample interaction: what the user types and what the program outputs. This is like a screenshot in text form. It removes ambiguity and helps the reader verify that the program is working correctly on their machine.

Design Choices. This is where you explain the why behind your code. Did you store data in a dictionary instead of a list? Explain the reason — perhaps dictionary lookups are faster for your use case. Did you break the program into multiple functions? Explain that it improved readability and made testing easier.

Trade-Offs & Limitations. Be honest about what your program does not do well. Maybe it doesn't handle invalid input gracefully, or it slows down with very large data sets. Acknowledging limitations shows maturity and critical thinking — two qualities that teachers and employers value highly.

Inline Comments in Your Code

Inside the Python source file, use inline comments (lines beginning with #) and docstrings (triple-quoted strings at the top of a function) to explain your reasoning. A good comment explains why a line of code exists, not what it does — the reader can see the what by reading the code. For example, # Use a set to eliminate duplicate entries quickly is far more useful than # Create a set.

One of the most important — and most overlooked — parts of presenting a program is explaining your design choices and trade-offs. A trade-off occurs whenever you pick one approach over another, gaining some benefit but giving up something else. In programming, almost every decision involves a trade-off, and documenting these shows that you understand your own code on a deeper level.

When you document a trade-off, use this simple template: "I chose [Approach A] over [Approach B] because [reason]. The downside is [limitation], but this was acceptable because [justification]." For example: "I chose a dictionary over a list to store player inventory because dictionary lookups by item name are O(1) instead of O(n). The downside is that items are not stored in the order they were collected, but for this game the order does not matter."

Let's walk through a complete example of presenting a finished Python program. The project is a simple quiz game that asks the user five trivia questions, scores their answers, and displays a final result. We will build every component of the presentation step by step.

Seeing side-by-side examples is one of the fastest ways to internalize what makes a presentation effective. The table below contrasts strong and weak examples across every component of a program presentation.

The skills you are building now translate directly into professional software development practices. The table below compares the classroom version of each presentation skill with its professional counterpart. If you continue into computer science, you will encounter these concepts repeatedly.

In advanced courses and professional teams, you will also encounter version control (Git), code reviews, and automated testing — all of which depend on clear documentation to function smoothly. The habits you develop now in presenting your programs will give you a significant head start when you reach those stages.