Reading code, the minimum: variables, functions and errors

The agent writes on screen: "I changed the function preco_encomenda in the file loja.py and fixed the error on line 8." And it asks your permission to save.

If you do not know what a function is, or where line 8 is, all you can do is say yes and hope. This lesson does not teach you to programme. It teaches you the minimum to understand what the agent shows you and to decide with your eyes open.

Ten lines of Python

An order at the bakery (a papo-seco is a Portuguese bread roll):

# Price of an order at the bakery
preco_papo_seco = 0.25

def preco_encomenda(quantidade):
    # Multiplies the quantity by the price of each one
    return quantidade * preco_papo_seco

total = preco_encomenda(12)
print("Twelve papo-secos cost", total, "euros")

When it runs, it prints: Twelve papo-secos cost 3.0 euros.

The names are Portuguese: preco is price, encomenda is order and quantidade is quantity. You can name things in any language you like. The words that belong to Python itself (def, return, print) are always in English.

There are four pieces here:

• Comment: the lines that start with #. They are notes for people. The computer skips them.
• Variable: preco_papo_seco = 0.25 stores the value 0.25 under that name. It is a labelled box. The = sign means "store", not "is equal to".
• Function: the block that starts with def. It has a name (preco_encomenda), takes an ingredient (quantidade) and gives back a result (return). It is a recipe written once and used many times.
• Call: preco_encomenda(12) uses the recipe with 12 rolls. The result is stored in another variable, total.

In Python, the spaces at the start of lines count: that is how it knows what belongs to the function.

The same in JavaScript

// Price of an order at the bakery
const precoPapoSeco = 0.25;

function precoEncomenda(quantidade) {
  // Multiplies the quantity by the price of each one
  return quantidade * precoPapoSeco;
}

const total = precoEncomenda(12);
console.log("Twelve papo-secos cost", total, "euros");

The same four pieces, in different clothes. The comment starts with //. The variable has const in front of the name. The function starts with function and what belongs to it sits between curly brackets { }. Lines end with ;. And names join the words with capital letters (precoPapoSeco) instead of underscores (preco_papo_seco).

Reading an error message

Imagine someone wrote preco_encomenda(doze) instead of preco_encomenda(12) (doze is Portuguese for twelve). Python answers:

Traceback (most recent call last):
  File "/Users/graca/experiencias/loja.py", line 8, in <module>
    total = preco_encomenda(doze)
                            ^^^^
NameError: name 'doze' is not defined

It looks frightening, but you read it from the bottom up:

1. Last line: what went wrong. NameError: name 'doze' is not defined means "I do not know anything called doze". The computer does not know that "doze" is 12; it only knows the variables that have been created.
2. Just above: the guilty line, with arrows ^^^^ under the part that failed.
3. Higher up: the file and the line number. loja.py, line 8.

In JavaScript the layout changes a little: the error (ReferenceError: doze is not defined) appears in the middle, and the place appears at the top and in the lines that start with at, in the form loja.js:9:30 (file, line 9, column 30). The idea is the same: what went wrong, in which file, on which line.

The diff: the most important thing in this course

A diff shows what changed between two versions of a file. It is like Word's "Track Changes", but in plain text:

 # Price of an order at the bakery
-preco_papo_seco = 0.25
+preco_papo_seco = 0.30

• Line marked − (often in red): comes out.
• Line marked + (often in green): goes in.
• Line with no sign: stays the same. It is there only to show you where you are.

Here the price of the papo-seco went from 0.25 to 0.30. Nothing else.

Why is this the most important thing? Because an agent can write three hundred lines in a minute, and you are not going to read three hundred lines. But you will read the diff of what it wants to change, before you say yes. The diff is the moment when you are the one in charge. In the next lessons you will see it many times.

 def preco_encomenda(quantidade):
-    # Multiplies the quantity by the price of each one
+    # Baker's dozen: anyone who takes 13 or more pays for one less
+    if quantidade >= 13:
+        quantidade = quantidade - 1
     return quantidade * preco_papo_seco

Before applying this, explain this diff in plain English: what comes out, what goes in and why. Do not change anything yet.