Anyone who has ever made a living writing code has probably had some version of the following drilled into their head: “Always write your code so the next person can understand it.” Every single coder has then gone on to do exactly the opposite, using cryptic variables and bizarre structures that nobody else could possibly follow. And every single coder has also forgotten the next part of that saying — “Because the next person could be you” — and gone on to curse out an often anonymous predecessor when equally inscrutable code is thrust upon them to maintain. Cognitive dissonance be damned!
It’s a tale as old as time, or at least as old as programming has existed as a profession. And by 1975, poorly written code was enough of a problem that an outfit called Edutronics put together the animated gem Critical Program Reading: Structuring an Unstructured Program. It’s apparently Part 1 of a larger series on structured programming techniques, and comes to us by way of [Alec Watson], host of Technology Connections on YouTube, by way of his second channel, the delightfully named Technology Connextras.
The film’s three minimally animated characters, each of whom could have been the villain in an episode of Scooby Doo, are tasked by a stern-sounding narrator to analyze a fragment of pseudocode that’s written in a concoction of COBOL, PL/1, and a bunch of other languages. The code is a hot mess, but our heroes muddle through it line by awful line, making it more readable by guessing at more descriptive variable names, adding structured elements, and making logical changes to improve the program’s flow. The example code is highly contrived, to be sure, but the business logic becomes much clearer as our team refactors the code and makes it far more approachable.
For as much as languages have changed since the 1970s, and with all the progress we’ve made in software engineering, the lessons presented in this film are still surprisingly relevant. We loved a lot of the little nuggets dropped along the way, like “Consistency aids understanding,” and “Use symbols in a natural way.” But we will take exception with the statement “Wrong means poor structure” — we’ve written seen plenty of properly structured code that didn’t work worth a damn. We also enjoyed the attempt at socially engineering a less toxic work environment: “Use tact in personal criticisms.” If only they could learn that lesson over at Stack Overflow.
It’s not clear where [Alec] found this 16-mm film — we’d sure like to hear that story — but it’s a beauty and we’re glad he took the time to digitize it. We’re consistently amazed at his ability to make even the most mundane aspects of technology endlessly fascinating, and while this film may be a bit off from his normal fare, it’s still a great find.
Same cycle of teaching, ignoring and regretting happens to every grad student to keep a lab notebook.
How I would have revised it, minimal cognitive load, no hard-coded constants, no go to label required…
NET-ORDERS = FILLED-ORDERS + BACK-ORDERS – RETURNS.
FRACTION-OF-RETURNS = RETURNS / NET-ORDERS.
IF FRACTION-OF-RETURNS IS GREATER THAN HR-REPORT-CUTOFF
THEN PERFORM HR-REPORT
ELSE IF FRACTION-OF-RETURNS IS GREATER THAN HR-WARNING-CUTOFF
THEN PERFORM HR-WARNING.
Would define:
HR-REPORT-CUTOFF = 1/3.
HR-WARNING-CUTOFF = 1/5.
And add a function HR-WARNING that ADDS ONE TO HR-WARNINGS where HR-WARNINGS is what I guess HRC (HR-COUNT?) was supposed to be. Isolating HR-WARNING into a separate function allows a centralized place to update, as opposed to likely multiple places.
This was a fun little example. I have legacy snippets of 15 lines or so from third parties that are resistant to significant factoring. Just when you think you wrap your head around it, you realize you’re misunderstanding it.
Why get HR (Human Resources) involved?
They wouldn’t know a character from an integer.
The Gerald Weinberg mentioned in the opening credits is likely Gerald M. Weinberg, author of the classic “The Psychology of Computer Programming” and many other excellent books.
https://en.wikipedia.org/wiki/Gerald_Weinberg
Yes, it certainly is that Gerald Weinberg. The videos came out of his consulting company Ethnotech. There are at least two others that they did.
This YouTube video was the first time I saw any of the films, and I happened to see it because I recently subscribed to the channel.
When I tell students how to code, I break it down to a few basic rules:
1) First thing (ALWAYS) is your full name and todays date. Leave a trace, give the next guy (probably you) a clue when and who commited this crime. If you don’t, I will haunt you in your dreams!
2) Make your code verifyable. Proof it by simple explanation, don’t pretend that “I’ve tried it twice, worked for me” is a proof. If it’s easy to understand you can not hide errors.
3) Make your code serviceable/maintainable. Needs rule 2.
4) Write your code so that you do not have to remember stuff or build up an mentally expensive model to change a tiny bit, without violating rule 2 and 3. Code should explain itself when read from top to bottom. You will forget all your great ideas after three weeks.
5) It’s easy to write complicated code, this is not a proof of your ingenuity, rather the opposite. Writing a complex program that is easy to understand and maintain is a craft and art.
6) Reduce the WTF. Increase the Awesome!
6) Your name should be a mark. People should raise their eyebrows and utter words of awe when they read/hear your name. Don’t be that guy where everyone slaps their head, crouches and mumbles some bad words.
When one thinks about this rules, a simple coding standard and best practice emerge automatically.
Oh, I forget one more important rule:
*) Laziness is no excuse. Especially stupid laziness.
I’m sure glad you didn’t mention documentation or flow charting!
B^)
I guess it also helps if you can count?
Starting from Zero or One?
B^)
“1) First thing (ALWAYS) is your full name and todays date. Leave a trace, give the next guy (probably you) a clue when and who commited this crime. If you don’t, I will haunt you in your dreams!”
Seriously, have you ever tried to contact a former developer of the program to complain about his code and tried to haunt him until he fixes it? I don’t think so, because you would have been in jail. :P
This one single point has already become obsolete at the end of the ’80’s, when job hopping became the norm.
“6) Your name should be a mark. People should raise their eyebrows and utter words of awe when they read/hear your name. Don’t be that guy where everyone slaps their head, crouches and mumbles some bad words.”
This should be number 7. However, I can tell you from long experience that it doesn’t matter. Even if you write the most perfect code, people will still slap their head, crouch and mumble bad words. Because of the Dunning-Kruger effect. People tend to think that they are smarter than they are. So even if you really ARE the singularity, i.e. the smartest and best developer ever, not susceptible to Dunning-Kruger, there will ALWAYS be people who do suffer from Dunning-Kruger, think they are smarter, and slap their head, crouch, and mumble bad words. And then rewrite your perfectly fine-working code. :)
And let me tell you: sometimes they will fail rewriting it. But always then it will still be your fault for having written such ‘bad’ code.
A writer’s intentions can only be read as intended by a reader who is able to understand those intentions of the writer.
1) Full name and date gives you often enough for a starting point.
People leaving is always a problem that you can factor in from the beginning, like vacation, sick leave and some people lowering the average level (somehow it has get to that average…). I have colleagues that work more since the end of the 80s in the same job and like it. A name and a date always leads to some information.
A blank line gives you nothing.
6 (0-based) mark: It’s not for the reaction of your colleagues – and I often have to slap my head with a mumble of “WTF?” when reading my own code.
The idea is that you build up an attitude.
Your work matters. Always aim for a good result, even if you do not have much time or resources. Doesn’t have to be perfect, just don’t be lazy or think no one will notice. Keep your attitude even when others don’t value your work, don’t see your effort, or find some errors (making errors is ok, repeating the same errors is stupid).
“1) First thing (ALWAYS) is your full name and todays date. ”
That’s what source control is for.
“We could read each other’s work!”
“Yeah, that’s a great idea!”
Thus was the code review born: not as easy then at it is now. I wrote COBOL for a bank about 15 years ago. A code review meant scheduling a meeting and bringing enough hardcopies (17″ continuous feed) for everybody to collectively pore over the code and provide feedback: no versioning systems, no diffs to isolate the changes… It’s so much better now with tools like git or Mercurial.
The pseudocode they came up with isn’t all that different from Python; punctuation characters used differently, and I was twitching at the VARIABLE-NAMES-CONTAINING-DASHES, but otherwise quite readable.
I definitely said “Python” under my breath when the announcer said “it’s too bad the computer can’t understand our indentation”.
I know some people still hate that aspect of the language, but you have to admit it was a bold choice.
Yeah. Now you can eyeball whitespaces down to the n-th level and guess what it matches three screens back. Take away one empty character, break everything.
We did this! About 25 years ago (eek!). Many pages of assembly language, four engineers, one week every 18 months or so. It absolutely had to be perfect. And it was. Hand-crafted assembly is so elegant!
I learned to write assembly language on a PDP-11/45. I would leave a page of code for the consultant who worked nights and I’d get it back with cross-outs, comments and exclamation points, all in red ink. Gradually I got better and one day he wrote “I’m beginning to think you might be able to do this.”
You did code reviews on paper a mere 15 years ago?!?!
NASA?
I remind myself of this film whenever I see code I can’t understand; sometimes the variable names are so cryptic I can’t even figure out what they refer to even if I know the problem domain. A lot of that stuff would be good candidates for the IOCCC :)
heh i’ve worked on a program for …golly, 21 years now… and i understand it fairly well but in the center of it is a record called a “POF” and i still don’t know what that was supposed to mean! :) in my head i pronounce it “point of reference” but i don’t think that could be it
IOCCC? The International Olympic Committee of Computer Coding?
International Obfuscated C Code Competition. A competition in which programmers vie to produce the most incomprehensible but useful C code possible.
In a way, you’re both right!
B^)
“But we will take exception with the statement “Wrong means poor structure” — we’ve written^H^H^H^H^H^H seen plenty of properly structured code that didn’t work worth a damn.”
i’m curious about this claim. i can’t say i relate to it at all. i mean, i’ve sometimes written code that was well-structure but didn’t work *on the first try* but i always found it to be “right” in that key way, i always knew what to do to make it work. it was just those first few typos away from working.
from other people, i’ve seen a *ton* of code that worked but was structured poorly. and as much that didn’t work (sometimes subtly) that was structured poorly. and of course i’ve written a bunch that worked but when i went to do something to it, i found it was almost impossible because it was structured poorly. in fact, a lot of times i thought it was structured well up until i tried to do anything with it!
Gah!!!
I recall programming in the late 70’s, early 80’s. We were stuck with limitations of the env (software or OS). We had limits on the length of variables names and limitations on where things could be (at least for asm language). I hated 5 character names (it’s trble – terrible or trouble) and Labels at column 1, asm instructions at col x, mnemonics at y, comments at z. Even in a HLL you had limitations.
I do agree with a style and that code should be ‘lite and airy’ (use spaces/NL to break code up) and if you code goes on for pages and pages think about breaking it up into functions.
At the moment I’m working through this (I added a dot to the front to retain the space that followed):
.CIDTA LDAA TRCS GET CONTROL WORD
. ASLA CHK THAT RDRF IS SET
. BCS CIDTA1 READ DATA IF SET
. ASLA LOOK AT ERR BIT
. BCC CIDTA2 RTN W/C CLR IF NO READ
* IF FRAMING ERR OR OVER RUN-READ
CIDTA1 LDAA RECEV READ
* RETURN W/CARRY SET & LDAA BITS SET
. SEC FLAG READ-NO WAIT ACOMPLISHD
CIDTA2 RTS
Yes, I’ve cleaned that up. A lot more space and the use of ;* as the start of comments (column 1 & end comments). I haven’t finished adding in the variable names for things like CR, LF, SP and Rx and Tx registers. ;-) Yes I do use longer names also.
Yeah, but – the satisfaction as you sit back, hands behind your head, light up a phat one and say to yourself, heh, they’ll never work out what the hell that doses
They are playing fast and loose with the equal operation in the comparisons. While the flow is better, but taking a “less than” and converting it to a “bigger than” instead of “bigger or equal than” is asking for a financial trouble.
Does anyone have a link to the other parts of this series? I’d love to watch them.