The shape of the lesson
By the end of the lesson, learners can
- Meaningful identifiers: Compare the two versions of the same algorithm.
- Comments: A comment is a note for human readers.
- Constants and subroutines: Each program in the lab has one mistake.
- Identifiers: meaningful names for variables, constants, arrays, procedures and functions.
- Comments: // in pseudocode; explain purpose, not every line.
- Constants: one place to change a fixed value.
- Subroutines: write once, call many times, test separately.
One picture every idea returns to
A maintainable program is easy for another programmer to understand, correct and update. Use meaningful identifiers for variables, constants, arrays, procedures and functions, so each name says what it holds or does. Add comments (starting with // in pseudocode) to explain the purpose of sections of code; the computer ignores them. Use constants for fixed values and procedures and functions to split the program into named, reusable parts.
Forty-five minutes, phase by phase
| Time | Phase | What happens in the room | Grouping |
|---|---|---|---|
| 0 to 5 min | Hook: predict | Open with the question in the title, Code for the next reader.. Programs are read far more often than they are written. Put the figure on the board: it is the one picture every idea in the lesson returns to. | Whole class, then pairs |
| 5 to 13 min | Teach and check: Meaningful identifiers | Compare the two versions of the same algorithm. | Whole class, then pairs |
| 13 to 21 min | Teach and check: Comments | A comment is a note for human readers. Model the worked example Useful or not? on the board, one line at a time. | Pairs |
| 21 to 30 min | Teach and check: Constants and subroutines | Each program in the lab has one mistake. Project tab 4 of the lab (Find the error) and let a student drive it while the class predicts. Model the worked example Improve this code on the board, one line at a time. | Cooperative Concept Mapping |
| 30 to 36 min | Check | The four Stage 1 questions from the student lesson, answered on mini whiteboards or by show of fingers. Re-teach the one most get wrong. | Individual, then whole class |
| 36 to 43 min | Plenary | The exam-style questions from Stage 2, one at a time: thirty seconds alone, then a random call. The feedback lines in the key give the examiner's wording. | Individual, random call |
| 43 to 45 min | Exit and homework | Set the worksheet below (6 questions, 16 marks). Learners self-assess against the objectives before they leave. | Individual |
Protect the parts that carry the learning
The sequence carries about fifty minutes of material, so the lab is driven by one student while the class predicts rather than explored freely. Times are a guide.
Protected: the check at 30 minutes. It is the only individual read on whether the key idea landed, and it is not cut.
Cut first if the build overruns: the last check in Constants and subroutines, never the check or the plenary.
In a 60 minute block: run worksheet questions 1 to 3 in class as a Rally Coach set and model both the hardest worked example and its check live.
Cooperative Concept Mapping
Teams receive the key terms on cards and arrange them on a large sheet, drawing and labelling the links. Compare maps between teams before showing the model map.
The full structure, with its variations and the other twelve, is on the cooperative-learning page.
What to head off, and how
| Trap learners fall into | Teaching move that pre-empts it |
|---|---|
| "Use good variable names" is too vague for a mark. | Say meaningful identifiers and explain the benefit: another programmer can see what each variable stores, so the code is easier to understand and update. |
| Comments are ignored by the translator, so they do not make the program run faster or slower, and they do not fix errors. | They help people. |
Writing maintainable programs: worksheet
6 questions, 16 marks. Written in the style of the papers; no past paper question is reproduced.
Identify three ways a programmer can make a program easier to maintain.
Explain why programmers use meaningful identifiers.
Rewrite this pseudocode to make it more maintainable.
A ← 0
FOR B ← 1 TO 7
INPUT C
A ← A + C
NEXT B
OUTPUT A / 7Explain the purpose of comments in a program.
Explain why each identifier is unsuitable: (a) Average Mark (b) Q for the number of questions answered (c) Total_Cost
A program uses the value 15 in several places as the maximum number of players. Explain the benefit of declaring it as a constant.
Answer key and marking notes
- Use meaningful identifiers (for variables, constants, arrays, procedures and functions).
- Add comments explaining the purpose of the code.
- Use procedures and functions (or constants, or consistent indentation).
- The name shows what data the variable stores or what the subroutine does.
- So other programmers (or the same programmer later) can understand, debug and update the code more easily.
- A comment explaining the purpose, e.g.
// average daily temperature for one week. - A constant, e.g.
CONSTANT DaysInWeek ← 7, used in the loop and the division. - Meaningful identifiers, e.g. Total, Day, Temperature.
- Declarations with suitable data types, e.g.
DECLARE Temperature : REAL.
- Comments explain what sections of code do (or why).
- They are ignored by the computer but help programmers understand and maintain the code.
- (a) It contains a space, which is not allowed in an identifier.
- (b) A single letter is not meaningful; it does not say what is stored (e.g. use QuestionsAnswered).
- (c) Underscores are not used in 0478 identifiers; use TotalCost.
- The value is given a meaningful name (e.g. MaxPlayers), so the code is easier to read.
- If the maximum changes, it is updated in one place, and it cannot be changed accidentally while the program runs.
6 multiple-choice questions on this lesson
From the topic question bank. Assign them in the app for a marked score in your gradebook, or run the topic as a class game.
A variable stores the number of failed login attempts. Which identifier is the most meaningful?
- AFailedAttempts
- BF
- CCount2
- DValue
Which statement about comments in a program is correct?
- AThey explain the code to people and are ignored when the program is translated
- BThey make the program run faster because the translator can skip lines
- CThey are checked by the translator, so they help to find syntax errors
- DThey are displayed on screen to the user when the program runs
A program contains the line Cost ← Price * 1.2 in five places, where 1.2 adds 20% tax. Which change makes it most maintainable?
- ADeclare
CONSTANT TaxRate ← 1.2and use TaxRate in all five places - BAdd a comment next to each of the five lines saying that 1.2 adds the tax
- CAsk the user to input the value 1.2 every time the program runs
- DReplace 1.2 with
6 / 5in all five places
Why does splitting a program into procedures and functions make it easier to maintain?
- AEach task is written once as a named block, so a change or fix is made in one place
- BProcedures and functions always run faster than the same code in the main program
- CCode inside a procedure cannot contain logic errors because it is tested automatically
- DProcedures and functions remove the need for comments and meaningful identifiers
This program works out the average mark for a class of 30.
X ← 0
FOR I ← 1 TO 30
INPUT Y
X ← X + Y
NEXT I
OUTPUT X / 30Which change makes it more maintainable without changing what it outputs?- ARename X to TotalMark and Y to Mark, and replace each 30 with a constant ClassSize
- BRename X to TotalMark and change the loop to
FOR I ← 0 TO 30 - CRename Y to Mark and replace
X / 30withDIV(X, 30) - DRename X to TotalMark and move
X ← 0inside the loop
Inside a loop that validates a password, the line Count ← Count + 1 runs each time a wrong password is entered. Which comment above this line is most useful to another programmer?
- A
// count the number of failed attempts - B
// add 1 to Count - C
// this line is a counter - D
// Count is an INTEGER variable
Quiz key
FailedAttempts says exactly what is stored, so the code is easier to understand and update. F is a single letter with no meaning. Count2 says it counts something but not what, and the 2 suggests other similar counters. Value could describe any variable at all.
Comments (starting with // in pseudocode) explain the purpose of code to anyone reading it, and the translator ignores them. Because they are ignored they do not change the speed of the program, are not checked for syntax and do not fix errors. Text shown to the user comes from OUTPUT statements, not comments.
A named constant explains what 1.2 means and means a change of tax rate is made in one place only. Comments explain the value but all five lines would still need editing. Asking the user every time adds work and the chance of a typing mistake. 6 / 5 is the same number written less clearly, still in five places.
A procedure or function is written once and called wherever it is needed, and its name says what it does, so the code is easier to understand and changes are made in one place. Subroutines are not faster by nature. Programmer-written code can still contain logic errors. Good names and comments are still needed inside subroutines.
Meaningful identifiers and a constant ClassSize (used in both places) make the code easier to read and update, and the output is the same. A loop from 0 to 30 reads 31 marks. DIV discards the fractional part of the average. Moving X ← 0 inside the loop resets the total each pass, so only the last mark is kept.
Saying what is being counted and why explains the purpose of the line. // add 1 to Count only repeats the code. // this line is a counter adds almost nothing. The data type is already given by the declaration, so the last comment does not explain this line.
What to project
The student lesson embeds these tabs. Open them full screen on the projector; every slider has a drag handle on the stage.
Slides for this lesson
A projectable deck for every pack is on the way. Until then, present the student lesson full screen: its sections, figure and lab tabs follow the same order as the plan above.