Asking Questions 101

Prep

• Read this article about Mental Models
• Review the Asking Questions workshop and the CYF Guide to Asking Questions on the curriculum.

Today we’re going to build on our formal language of developer questions. We began with this basic format:

1. What I did
2. What I expected
3. What actually happened

This format helps to find the discrepancies between expectations and reality. (This is the gap in our understanding.)

It’s also an efficient way to share our current understanding with others. Now we’re going to use this to write a really good bug report. A well-written bug report can help developers identify, reproduce, and fix issues more efficiently. We will follow this basic format:

1. Steps to Reproduce (What I did)
2. Expected Behavior (What I expected)
3. Actual Behavior (What actually happened)
4. Environment Details 🆕

Clarity is our goal

Exchanging incomplete information sets 30m

😎 Useful questions -> colleagues enjoy answering -> get solutions promptly -> make lots of progress -> good performance 😰 Not useful questions -> colleagues avoid answering -> don’t get solutions -> take much longer -> performance appears poor

Steps to Reproduce

When you’re writing a bug report, you need to be able to reproduce the bug. This means you need to be able to make it happen again. The person reading the report needs to be able to follow your steps and cause the same error.

Here’s an example of steps to reproduce:

1. Go to my deployed site at https://my-site.com
2. Click the “Login” button top right
3. Choose “Sign in with GitHub”
4. Authorise with GitHub and be redirected back to the site
5. Login page error says To confirm your identity, sign in with the same account you used originally.

Bad bug reports

Why are these not useful?

Expected behavior

What you expected to happen

When you’re writing a bug report, you need to be able to explain what you expected to happen after you executed the steps you just described. You might feel this is so obvious that you don’t need to write it down, but this assumption is drastically, drastically wrong.

Here’s an example of expected behavior:

“I expected to be able to log in with my GitHub account and be redirected to the logged-in view of my dashboard on my site.”

Actual behavior

What actually happened

Here’s an example of actual behavior:

“Instead, I was redirected back to the login page with an error message that says To confirm your identity, sign in with the same account you used originally.”

Error messages

What the computer told you

Have you ever considered, and this is just a wild idea, reading the error messages that your computer gives when it goes wrong?

Just kidding! We know all trainees are implacably opposed to reading error messages. But here’s the thing:

1. When you’re writing a bug report, you need to include the error messages you’re seeing. This is crucial information for anyone trying to help you.
2. You also need to read the message yourself first. If you cannot understand it, you need to say what you don’t understand about it. This is the gap in your understanding that you need help with.

Missing script: "dev"
npm ERR!
npm ERR! To see a list of scripts, run:
npm ERR!   npm run
npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/student/.npm/_logs/2024-02-26T19_28_05_701Z-debug-0.log

Error messages aren’t always correct, but they are a valuable clue.

1. Read the error message
2. Identify suggestions
3. Find out what they would do (this also means being able to form a hypothesis to test)
4. Then (maybe) do them.

Environment Details

The conditions in which the bug occurred

When you’re writing a bug report, you need to be able to describe the system you were using when you encountered the bug. Because all these details matter!

Here’s an example of environment details:

VSCode on Windows 10, Node v14.15.4, NPM v6.14.10, React v17.0.1, deployed to Netlify.

Let’s improve a bug report together to understand why details like this matter.

Iterative improvement of a bug report 15m

🐛 Bug Report Fail

Bug: I can’t create any files in my project I’m trying to create files in my repo but it just errors. I don’t know what’s wrong. Please help me!

This is a terrible bug report. Popcorn around the room and name four problems with it.

🐛 Bug Report Improvement 1

OK now we have some more information given. We’ve got some steps to reproduce and some expected and actual behaviour. But it’s still not great.

🐛 Bug Report Improvement 2

🐛 Bug Report Final Form

See how much easier is to fix in the final form? What is the bug in this report?

Wrapping up

Recapping the key points:

Include as much context as you can, including links, line numbers, sample code, etc. Use code blocks to mark up your code. If you use screenshots, they should only show the visual render (never screenshot code - paste code as text).

🧑🏾‍💻🙋 Bug reports contain

1. 🔗 Links 👍
2. 🎯 Objectives - what are you actually trying to do? 👍
3. 🖼️ Screenshots of UI if relevant 👍
4. 📝 Code blocks 👍
   • In Slack, proper code snippets get syntax highlighting and can be collapsed vertically - remember to 🧵 use threads too
5. 🪸 Environment details 👍
6. 📷 Screenshots of code 🙅

📚 Further reading

• How to ask
• The programming duck
• Asking Questions
• Reading Error Messages
• Writing the perfect question
• Smart Questions NOTE: this is an old-fashioned text so it’s very blunt. It is also really honest and maybe that is helpful for some people.

🎮 Playing computer

💡 Purpose

This workshop is designed to develop your understanding of playing computer. Playing computer means simulating how the computer executes our code. We “step through” the code, line by line, and work out what the computer does when it follows each instruction. Once we develop a better intuition for how our code runs it becomes easier to debug code, reason about it and write more complex programs.

During this session, you will:

Resources

You will need:

• A piece of paper saying “memory” - where we store variables
• A piece of paper saying “console” - where we print to the console
• Some example programs like the ones here 👉 Playing computer workshop
• [Optional] A set of functions in envelopes ( this isn’t essential but a nice thing to have to reinforce the idea of instructions being “opened” up when a function is called )

( If you don’t have any paper/pens you can create plain text files for “memory” and “console” and write your work out in there! )

🧰 Setup

1. Split up into groups of 2 or 3 at most.
2. Start with the first example ( e.g. example-0.js )
3. Each person will need to take responsibility for a particular frame. One person will be assigned the role of global frame, for example. If there are other function declarations, someone else will “play” that frame too.

🍲 Warm-up

Start with the program in example-0.js. There is only one frame to play here - the global frame, as there are no other function declarations and calls in the file.

• One person will “play” the Global frame
• This person will step through the code in example-0.js using the rules of execution below.
• Other members of the group can watch and provide support as they go through the code.
• Once you’ve finished you can change some of the values/variables and then someone else can play the global frame too
• ❗ After you’ve finished playing computer with the program, you should check your memory sheet and console sheet by using the Python visualiser

Rules of execution

Rule 0

Only one person can be sat at the table at a time ( where we write to the memory sheet/console sheet)

Rule 1

Start reading code from top to bottom, one line at a time

Rule 2

Write and update variables in memory as you go along For example, if the program says:

let a = 32;

You would write down “a : 32” on your piece of paper saying “memory”

Rule 3

If a function is called the person “playing” this frame takes the seat and we jump to the instructions in that function, using Rules 1 and 2.

Rule 4

When a function returns or finishes execution this person leaves their seat and the previous person sits down again.

You may need to play computer like this a few times before you get used to this way of thinking about the code. Make sure you swap roles so others get the chance to play a particular frame.

📝 Check your understanding

Doing this activity by hand is a great way to start thinking about how your code runs. Once you’ve gone through this activity and played computer with pen and paper, you can check what you’ve got on your piece of paper by playing computer with the Python Tutor code visualiser

Learning to evaluate your understanding

🎓 Instructions

This workshop aims to check your understanding.

Each task will explain whether or not you should run the code.

• For each task, use your prep materials to help you with the questions.
• You can also use documentation to look up any functions that are unfamiliar.
• Don’t use ChatGPT or any other AI tool to help you. We are practising how to check our own understanding. You are finding out what you need to work on. Make notes as you go along to help you focus what to work on in study group.

🧰 Setup

👉 This workshop lives on CYF-Workshops on GitHub

1. Get into pairs or groups of up to three.
2. Make sure you have a clone of the CYF-Workshops repository on your local machine

Each file contains a different problem at a particular level. Start this project at Level 100 and then move up through the levels: level 200, 300 …

🏁 Go to Level 100