BAS-220 · Lesson 10 of 12 · 21 min

Reading someone else's program

▶ Video coming soon A video version of this lesson is on the way.

Tilden Hall's VAV boxes were not Quillon's work. Their controllers had been installed in the 2009 DDC conversion by another contractor, since bought by a larger firm, and their programs had been edited by at least two people since. On Saturday, October 31, Sophie brought one of them to the workshop: the program for VAV-1-08, the box serving room 108 on the ground floor. She chose it because Gus had mentioned that room 108 was often uncomfortable, and because, as she put it, "every program you ever touch will have been written by someone else, including the ones you wrote yourself a few years ago." Twelve days later, as BAS-110 described, room 108 became the subject of a too-hot complaint, and Callie already knew its program. This lesson covers how to read a program you did not write: where to start, what to look for, and how to record what you find without breaking anything.

Start with what the program is supposed to do

Before opening a program, Sophie looks for the documents that say what it should do: the sequence of operations from the original design or the last retrofit, the controls drawings and point list, any commissioning reports, and the service history. The sequence is the most valuable, because it turns the question from "what does this code do?" into "does this code do what the sequence says?" For VAV-1-08 there was a 2009 sequence in the college's files, two pages long, and a point list with eleven points. There was no change history.

If there is no sequence, the reader must build one from the program and the equipment, and should write it down as they go. Sophie's advice was to write it in plain sentences, like the sequence in lesson 2's damper page, and then check each sentence against the program. A program that cannot be described in plain sentences is a program with a problem.

Documents to gather before reading a program.
DocumentWhat it gives the readerVAV-1-08
Sequence of operationsWhat the program is meant to do2009 sequence, two pages
Point listNames, types, ranges and terminals of the pointsEleven points
Controls drawingsWiring, device locations and equipment detailsBox schedule with airflows and coil data
Commissioning and balancing reportsAirflows and settings as tested2009 balancing report
Service history and change logWhat has been changed, when and whyNone found
Backups of earlier versionsWhat the program used to beOne undated backup on the college server

Read from the outputs back

A program can be read from its inputs forward or from its outputs back. Reading forward is natural for writing; reading backwards is usually quicker for understanding. Pick an output, such as the damper command or the hot water valve, and ask what decides its value. Find the line or block that writes it, then the values that line uses, then what decides those, and so on back to inputs and constants. Each output traced this way gives a short chain that can be written down as one sentence of the sequence.

The VAV-1-08 program as found, in the box controller's own text language. PI(process variable, setpoint, gain, integral time, action) is the controller's PI function; the apostrophe marks a comment.
PROGRAM VAV_1_08
  ' 2009
  IF OCC THEN
    CLGSP = ZNSP + 2.7
    HTGSP = ZNSP - 2.7
  ELSE
    CLGSP = 82
    HTGSP = 59
  ENDIF
  CLGLOOP = PI(ZNT, CLGSP, 4.4, 300, DIRECT)
  HTGLOOP = PI(ZNT, HTGSP, 5.6, 300, REVERSE)
  FLOWSP = 0.4 * VMAX + CLGLOOP / 100 * (VMAX - 0.4 * VMAX)
  IF SUMMER_OVR THEN FLOWSP = VMAX
  DMPR = PI(FLOW, FLOWSP, 2, 60, DIRECT)
  HWV = HTGLOOP
  ' IF HTGLOOP > 50 THEN FLOWSP = 0.5 * VMAX
END

Callie traced the hot water valve first. HWV, the valve output, was set to HTGLOOP. HTGLOOP was a reverse-acting PI loop on zone temperature against HTGSP. HTGSP was the zone setpoint minus a margin when occupied, or a fixed setback value when not. So the sentence was: the reheat valve opens on a heating loop as the room falls below the heating setpoint. Then the damper: DMPR was a PI loop holding measured airflow at FLOWSP, and FLOWSP was a minimum airflow plus a share of the rest, rising with the cooling loop. The sentence: the box holds a minimum airflow and increases it as the room rises above the cooling setpoint, up to the maximum. That was a single-maximum VAV reheat sequence, the most common kind in buildings of its age, which lesson 12 explains.

Magic numbers

A magic number is a constant in a program with no name and no comment, whose meaning the reader has to guess. VAV-1-08 had several. The 0.4 in the airflow line was the most important: it set the minimum airflow as 40 in 100 of the maximum. The gains and integral times in the PI calls were others. So were the unoccupied setpoints.

Worked problem

Decoding a magic number

The box schedule gives VAV-1-08 a maximum airflow, VMAX, of 320 cfm. What minimum airflow does the program's 0.4 give? What airflow setpoint does the program calculate when the cooling loop output is 40?

Show solution
  1. Minimum: 0.4 × 320 = 128 cfm, which the balancing report rounded to 125 cfm.
  2. At cooling 40: 125 + 40 ÷ 100 × (320 − 125) = 125 + 0.4 × 195 = 203 cfm.

Answer: A minimum of about 125 cfm, matching the balancing report, and 203 cfm at a cooling loop output of 40. The magic number turned out to be right; it simply needed a name, VMIN, and a comment citing the balancing report.

Not every magic number is right. A gain typed during a long-ago tuning session, a setpoint that once suited a tenant who has left, or a limit chosen to stop a complaint may all survive in a program for years. Each one deserves a question: where did this come from, and is it still right? Sophie's rule was not to change any of them while reading, only to list them.

Dead code, commented-out code and leftovers

Programs that have been edited over the years collect leftovers. VAV-1-08 had two. The line beginning with an apostrophe was a commented-out instruction that would have halved the airflow when heating was above 50, a fragment of what looks like an attempt at a dual-maximum sequence that someone had started and abandoned. The line IF SUMMER_OVR THEN FLOWSP = VMAX would force the box to full airflow whenever a point called SUMMER_OVR was true. Callie searched the point list and the front end and could not find SUMMER_OVR anywhere. The controller still had it as a local variable, defaulting to false, so the line did nothing, unless someone wrote to it.

Leftovers like these are dangerous for two reasons. They confuse the reader, who must work out whether they matter. And they can wake up: a technician who later creates a point with the same name, or a front end that writes to an old variable during an upgrade, could suddenly force every box in the building to full airflow. Sophie marked both lines for removal in the next planned change, with a note of what they had been.

Common leftovers in edited programs.
LeftoverHow to recognize itRisk
Commented-out codeLines marked as comments that look like instructionsConfusion; may be re-enabled without understanding
Dead branchesConditions that can never be trueWasted reading time; may wake up if inputs change
Orphan variablesNames used in the program but not found in the point list or front endHidden overrides that can be triggered by accident
Duplicate logicTwo places that write the same outputThe later one wins; the earlier one misleads
Test valuesFixed values where an input should beEquipment controlled by a constant left from testing

Compare versions

If an earlier backup exists, comparing it with the running program shows what has changed. Most tools can export programs as text, and text comparison tools, often called diff tools, show added, removed and changed lines side by side. For VAV-1-08, the undated backup on the college server differed from the running program in two places: the heating gain was 6 in the backup and 10 in the running program, and the commented-out line was not in the backup. Somebody had increased the heating gain and started, then abandoned, a sequence change. Without dates or notes, nobody could say who or why.

Comparing the program in the controller with the program in the front end's database or the contractor's files is also worth doing. They should be the same. When they are not, the next download from the database will silently undo whatever was changed in the controller, which is how fixes disappear.

Record, don't fix

The hardest discipline in reading someone else's program is not to fix things as you go. A change made while reading has not been thought through against the whole program, has not been tested, and is not recorded in the sequence. Sophie's practice is to keep a findings list while reading: each item with the location in the program, what it does, what the sequence says, the risk, and a recommendation. Changes are then planned, tested in simulation as lesson 11 describes, and made together with a backup and a change log entry.

Callie's findings list for VAV-1-08.
FindingLocationRecommendation
Minimum airflow as magic number 0.4Airflow setpoint lineName it VMIN with a comment citing the 2009 balancing report
Heating gain 10 differs from backup 6; no recordHeating PI callCheck heating loop behavior by trend before deciding
Orphan variable SUMMER_OVR forces full airflowOverride lineRemove at next planned change
Commented-out partial dual-maximum lineLast lineRemove; consider a proper dual-maximum sequence (lesson 12)
No comments, author or dateWhole programAdd a header and section comments
Unoccupied setpoints fixed in codeSetpoint sectionMove to named points that operators can see

Callie asked how long it would take to read every box program in Tilden that way. Sophie's answer was that most of the boxes were copies of the same program, so reading one carefully and comparing the others against it would find the differences quickly. In a building with dozens of copies, the copies that differ are where the problems are.

Habits that make your own programs easy to read

Reading other people's programs is the best training for writing readable ones. The habits Sophie listed by the end of the morning were a header with the equipment, the sequence reference, the author and a change history; section comments that say what and why; named constants instead of magic numbers; no commented-out code left behind; one place, not two, that writes each output; and a backup of every version with its date. "Write every program," she said, "for a tired technician reading it on a cold roof at midnight. One day that will be you."

Asking the people who know

Programs are not the only record of a building. Operators, facility managers and the technicians who serviced a system before often know why something was changed, even when nothing was written down. Callie asked Nell about the heating gain in VAV-1-08. Nell remembered that a cold-room complaint in room 108 had led a technician from the previous service contractor to change some settings one winter, probably around 2019, and that the room had been uncomfortable on and off ever since. That did not prove the gain was wrong, but it explained when it changed and why, and it told Sophie to look at the heating loop's trends on a cold morning before deciding anything.

Sophie's advice was to ask early and to write the answers down, with the name of the person and the date, because the memory of a building leaves with the people who hold it. A short conversation with an operator can save hours of reading, and it often reveals the complaint that a mysterious change was meant to fix, which is usually the real problem to solve.

Questions for operators and facility staff before reading a program.
Question to askWhat it can reveal
Has this room or unit had complaints?The problem that changes were made to fix
Who has worked on it, and when?Which contractor or technician to ask about changes
Does it behave differently in winter and summer?Settings tuned for one season
Has anything been replaced?New devices with different ranges or directions

Common mistakes

  • MistakeOpening the program before finding the sequence and drawings.

    InsteadGather the sequence, point list, drawings and history first, so you can compare code with intent.

  • MistakeReading from the first line forward when trying to understand an output.

    InsteadTrace each output back to its inputs and write one sentence for it.

  • MistakeChanging things while reading.

    InsteadKeep a findings list and plan, test and record changes separately.

  • MistakeIgnoring variables that are not on the point list.

    InsteadSearch for every name; orphan variables can be hidden overrides.

  • MistakeAssuming the controller and the database hold the same program.

    InsteadCompare them, so that the next download does not undo an unrecorded fix.

Summary and key terms

  • Every program you touch was written by someone else, including your own older work.
  • Start with the sequence, point list, drawings, reports and history; build a sequence if none exists.
  • Trace outputs back to inputs, and describe each as a sentence of the sequence.
  • Magic numbers need names and sources; some are right, some are relics.
  • Commented-out code, dead branches and orphan variables confuse readers and can wake up.
  • Compare versions to see what has changed, and compare the controller with the database.
  • Record findings without fixing them on the spot; change only with planning, testing and a backup.
Sequence of operations
The written description of what a control system should do.
Magic number
An unnamed, uncommented constant whose meaning must be guessed.
Dead code
Program logic that can never run or never has an effect.
Orphan variable
A name used in a program but not defined as a known point or documented value.
Diff
A comparison of two versions of a program that shows added, removed and changed lines.
Findings list
A written list of what a program review found, with locations and recommendations.
Single-maximum sequence
A VAV reheat sequence in which reheat happens at the box's minimum airflow.

Practice problems

Work each problem on paper first, then reveal the answer to check.

  1. A box with a maximum of 640 cfm has a minimum of 0.4 × VMAX. What is the minimum?

    Show answer

    About 256 cfm.

  2. In VAV-1-08, what does HWV follow?

    Show answer

    The heating loop output, HTGLOOP.

  3. What is an orphan variable, and why is it risky?

    Show answer

    A name not on the point list or front end; it can be written by accident and act as a hidden override.

  4. Why trace from outputs back?

    Show answer

    Each output gives a short chain to inputs that can be written as one sentence and checked against the sequence.

  5. What should you do with a gain you suspect is wrong?

    Show answer

    List it as a finding, check behavior by trend, and change it only through a planned, tested change.

Lesson quiz · 5 questions

Score 60% or more to complete this lesson.

Take the quiz