Programming Problem Solving Walkthrough

A programming problem solving walkthrough is a written guided description of the journey from a problem to a solution. It aims to teach how to solve programming problems in a methodical and thoughtful manner using the model. In other words, the knowledge to be learned is focused on the "how", and not on the programming language per se.

The walkthrough, as a teaching method, is based on two concepts: worked example from learning sciences and literate programming from computer science.

A worked example is a step-by-step demonstration of how to solve a problem. Learning scientists found out that worked examples are most effective for novices (i.e., the audience of a walkthrough), while performing problem-solving is more beneficial for experts. There are multiple ways of presenting and supporting worked examples, and one of the evidence-based techniques is to include sub-goal labeling, which is about labeling groups of steps in the worked example.

Literate programming by Donald E. Knuth is a programming paradigm in which a program is written as interspersed snippets of executable code and text. The text, which is written in ordinary human language, explains the logic of the code and explains the programmer's thoughts and decisions. Thus a program is perceived much more like an essay.

The walkthrough combines these two powerful ideas for learning the craft of problem solving by programming. It uses the programming problem solving model and its supplements to give a framework for establishing the learning objectives, as well as defining the walkthrough's structure and flow.

The learning objective of a walkthrough is rooted in one of the phases (for example, acquiring the ability to use a specific design strategy). That's in addition to the always-present learning objective of mastering the instrumentation of end-to-end problem solving.

Many times the solving process is hidden, and one gets only the final result, the executable code. Therefore, an essential feature of a walkthrough is making the reasoning explicit, as suggested by literate programming. In other words, it brings the solving process to the surface and documents the train of thought of the problem-solver as they go through each of the phases. In fact, a walkthrough aims to prompt self-explanation by the learners.

A similar but different flavor of a walkthrough is one that is developed by the learners. They choose a programming problem and fill in a provided walkthrough template. The learners improve their ability to solve problems by explicitly documenting their own process.

This page was written with Python in mind, with Jupyter Notebook that serves as the medium for the walkthrough. Notebooks are natural for literate programming, with their capability to mix text, media, and code in cells. Nevertheless, a walkthrough is a teaching method which is beyond one programming language or another, and it can also be developed as a source code file.

Walkthroughs as open education resources are published here:

Few (opinionated) Principles and Practices

  • A walkthrough is an active learning activity. It is similar to a tutorial in the sense that it is most effective if the reader follows along by actually performing the tasks being described. In our particular case the tasks are based on the phases of the problem-solving model.

    For example:

    • Reinterpret the Problem phase - suggest input-output instances.
    • Design a Solution phase - write about choosing a data structure, what attributes make it fit.

    While it is important to focus on one particular phase so as not to overwhelm the learner, other phases should not be neglected. To keep the student engaged throughout the walkthrough it is suggested to use less demanding, yet active, tasks.

    Tasks suggested by phase appear later on this page.

  • The walkthrough is designed to achieve teachable moments, in which it leads the learners to a point where they discover or apply a concept, an idea or a technique from the learning objectives.

  • At the same time a walkthrough must manage cognitive load, with a great focus on the external one.

  • The walkthrough is a "better version of reality" that focuses on the learning, and not on accurate journaling of the problem solving process. By its nature, this process is often messy and non-linear. Meanwhile, the goal of the walkthrough is to guide the learner through solving the problem in a logical and clear manner, without recording all the twists and turns. In that sense, the walkthrough is a "better version of reality", in which the actual steps are filtered and distilled to support the designer's learning objectives efficiently.

  • The text and code should be written in expository style. Even if a program has a hierarchical (tree) design, it this might not mean that this structure is the best for its development.

    A problem should be solved and explored in a psychologically correct order, following the solver's "stream of consciousness". The objective is to go through the process of solving, and a walkthrough inherently performs a "linearization" of this path. As Donald E. Knuth wrote:

    My experiences have led me to believe that a person reading a program is likewise, ready to comprehend it by learning its various parts in approximately the order in which it was written.

  • The walkthrough is intended to be perceived as a dialogue with the learner. Of course, this is impossible due to the non-interactive format, but aimed as aspiration.

  • Walkthroughs are not stand alone but should be considered in context of a unit or a course. After the learners worked on the walkthrough, a wrap-up session (that might include a presentation or live coding of partial or complete solution) should take place.

  • Use of real-word problems or cover story can increase the motivation of the learners.

  • It is advised to limit the external permitted materials for the learners.

Checklist / Rubric

This is an opinionated checklist of all the points that a decent walkthrough should fulfill. It refers to the complete walkthrough after a learner performs all the tasks. It is up to the developer to decide which parts are already presented at the beginning and which are left to the learners.

  1. General

    • Using incremental development
      • Get something working and keep it working:
      • First writing code in cells, testing it and only then encapsulating into functions
  2. Reinterpret the Problem

    • Rephrasing the problem statement in their own words
    • Writing the solution contract
    • Describing the problem as a black box - what should be the input and output
      • Meaning and (Python) type
      • One or few input-output pairs of concrete instances (it doesn't need to be comprehensive right now, it is not the Test phase)
  3. Design a Solution

    • Ultimately, a walkthrough should break down the problem into hierarchical sub-problems; in other words, it should present an outline of the solution decomposed into sub-problems.
    • Following the DRY (Don't Repeat Yourself ) design principle - Identifying repeating sub-problems
    • Reasoning about data (representations)
      • A mapping between the information in the problem/solution domain to a data-structure (either primitive or composed, flat or nested) in Python
      • Describing the meaning of the data structure, the relationship between its components and the required operation (a.k.a questions)
  4. Code

    • Transforming well the design into code
    • Pythonic Code - Python Idioms
    • Style & Documentation
      • PEP8
      • Meaningful Names
      • Using Comments
      • Using Helper Functions when needed (e.g., for following DRY)
  5. Test

    • Writing comprehensive test cases
      • Black box (e.g., trivial cases, simplest non-trivial cases, edge cases, corner cases - but it is not mandatory to write the type)
      • White box - coverage / path-complete
    • Each test cases is consists of:
      • Scenario - Using the language of the problem phase/domain
      • Instance - Concrete Input-Output pairs
    • The test case follows the simplicity principle - the instance(s) should be the simplest possible to test the scenario.
  6. Debug

    • Following the empirical approach for debugging (reproduce, diagnose, fix, repeat, reflect)
    • Diagnose - Focus on reasoning on the available clues (e.g., the bug itself - input/output and trace-back, reading the code with a critical eye, using the print function)
  7. Evaluate & Reflect

    • Evaluation
      • Sincere and sharp evaluation of:
        • Functionality
        • Design & Code
        • Readability, Style & Documentation
    • Reflection
      • Alignment between the presented problem solving process and the takeaways
      • Postmortem of the problem solving or debugging process
      • Self-debugging - what the programmer can learn from solving this problem.
  8. Solution Program - Solving the Problem

    • Copy-paste and organize all the necessary code for a complete solution of the problem in one cell or py file, and execute it to solve the original problem. Note that it might require asking the learners to combine code snippets from different parts of the notebook.
    • The code in the solution section is self-contained for execution, and doesn't depend on other snippets of code from the previous steps.
    • This section also contains tests of the solution code.

Tips for Developing a Walkthrough

The Carpentries Curriculum Development Handbook is an excellent resource for how to develop a curriculum in computing and what it says is equally applicable to developing a walkthrough.

  1. First of all, set the learning objectives using the programming problem solving model terminology.

  2. Form a problem - choose an algorithmic one or real-world one.

  3. Solve the problem, document your process based on the model, pay attention to your mistakes and bugs.

  4. Reflect on your problem solving process and try to distill it into steps and teachable moments.

  5. Refactor your code and remove clutter. While it doesn't have to be the best possible, make sure to adjust for the required ability of your learners.

  6. Write an outline of the walkthrough and embed your code in the relevant sections. Validate it with a checklist.

  7. Decide what tasks the learners should do, making sure they align with the learning objectives.

  8. Write the complete text of the walkthrough that guides the learners. It is advised to use the plural first person pronoun "we".

  9. Run a pilot of the walkthrough on a small group of learners.

  10. Repeat and improve!

Suggested Tasks by Phase

  1. Reinterpret the Problem

    • Phrase the problem in your own words
    • Write three examples of input-output pairs for the problem
    • Write the solution of the problem or of a function (in the docstring)
  2. Design a Solution

  3. Code

    • Write code according to a design (either done by the learner or given in the walkthrough)
    • Read the given snippet of code and...
      • Draw an environment diagram
      • Answer questions about it
      • Write a docstring to a function
      • Give meaningful names for variables in the code
      • Extract its design (e.g., write a "design tweet" with a maximum of 240 characters)
      • Discuss its design - why did the solver choose that particular design and not another, especially pay attention to the data structures
  4. Test

    • Write test cases for the problem or function
  5. Debug

    • Fix a bug in a given piece of code
    • Describe a bug you had while solving the problem, and explain how you fixed it
  6. Evaluate & Reflect

    • Evaluate a given piece of code
    • Evaluate your code
    • Reflect on your problem solving process
  7. Repeat & Improve

    • Refactor a given piece of code (e.g., because of speed or design issues)

Additional ideas and inspiration for tasks can be found in the Exercise types chapter from "Teaching Tech Together" and in the Catalog of pedagogical patterns chapter from "Teaching and Learning with Jupyter".


  • A Walkthrough is a written guided description of the journey from a problem to a solution.
  • It aims to teach how to solve programming problems in a methodical and thoughtful manner using the model.
  • The conceptual roots of the walkthrough as a teaching method are the ideas of worked examples and literate programming.
  • It is designed to prompt self-explanation by the learners.
  • Jupyter Notebook serves as the medium, and it includes active learning tasks.


Copyright © 2019 Shlomi Hod.
All rights reserved.

results matching ""

    No results matching ""