UPI Study › Courses › C++ Programming › Free lessons › Lesson 2.3 Free with a free account
Professional Habits: Readability Standards
C++ Programming · Chapter 2: Getting Started with C++Section 2.3 · lesson 10 of 84video coming soon
← Preparing Your MachineNext lesson: Representing Quantities →
In this lesson
Indentation, annotation and readability standards.
- Lay out braces and indentation to match structure
- Name things by this course's conventions
- Judge which lines deserve a comment
- Apply the spacing and line-length rules
Transcript
Everything said in the video, section by section (1,592 words). Read along, or search it.
Opening Question
Who Is Your Code Written For
Here's a question worth asking early: who is your code really written for? Indentation, spacing, naming and comments change nothing about the program the compiler produces. They're stripped away, or ignored, before any machine instruction exists. They're entirely for human readers. And the reader who reads your code most often, and least charitably, is you, three weeks later.
Hurried Example
Compiler Ignores Layout, Runs Identically
The compiler treats your text as a stream of symbols. Spaces and newlines just separate one symbol from the next. Comments are removed before translation even begins. You could write a whole program on one enormous line, and it would run identically. This program was typed in a hurry. It reads a limit, and adds up the even numbers up to it. It compiles, and gives the right answer: for a limit of 10, the even numbers add up to 30.
Worked Example
Same Program, Written to Standard
Now the same program, written to the standard. The hurried version hides three things this one states plainly: that only even values are added, that the result is a total, and where the repetition begins and ends. Nothing was added except layout, names, and one line of explanation. And this is the one you could safely change under time pressure. The cost of unreadable code is never charged all at once. It arrives as seconds lost rereading a condition, or an afternoon repairing a change made on a wrong assumption. The fix costs nothing, because the layout takes just as long to type either way. Same input, same answer.
Indentation Rules
Four Spaces, Aligned Braces, One Statement
Indentation shows nesting. Every time a construct opens a body, everything inside moves one level right, and comes back when the body closes. Done consistently, the left edge of the text becomes a picture of the program's structure, readable without reading a word. The standard here has four parts. Four spaces per level, using spaces, not tab characters, because tabs display differently in different editors. The opening brace goes on its own line, in the same column as the statement that owns it, and the closing brace lines up beneath it. So a missing brace is visible, not deduced. Braces are always written, even around a one-statement body. And there's one statement per line, because two on one line hide one of them.
Common Mistake
Braceless Bodies and Misleading Indentation
Here's why one-statement bodies still get braces. C++ lets you leave them out when a body is a single statement. Today, you write: if is late, fee equals fifty. Tomorrow, you add a second line under it, and indent it to match. Only the first line is governed by the condition. Nobody here is late, yet the warning count went up. The indentation now lies about the structure. And it compiles without a word, here even with warnings on, because indentation means nothing to the compiler. Some compilers can flag misleading indentation, but don't count on it. Braces from the start remove the trap entirely.
Brace Styles
Two Styles, One Consistent Choice
You'll meet two brace styles. With the brace on its own line, opening and closing braces align, so an unbalanced one is easy to spot. That's the style used here. With the brace at the end of the line, code is more compact, and it's very common professionally, so be able to read it comfortably. Its opening brace is easy to miss. The choice is a convention, not a truth. What's not negotiable is consistency: a file that switches styles is harder to read than one that sticks to either.
Naming Conventions
Four Name Forms and Name Length
A name is the cheapest documentation there is. It's written once, read constantly, and unlike a comment, it can't drift out of date without the compiler noticing. The goal is that a line of your program reads aloud as a statement about the problem, not a puzzle about notation. This course uses four forms. Variables are camel case: item count, average score, is valid. Functions are camel case too, starting with a verb: compute total, read limit, has expired. Constants are capitals with underscores, like max items and tax rate. And type names are Pascal case, every word capitalized, like customer record. One more rule cuts across all four: a name's length should match how far it travels. A counter that lives for three lines may be i. A value used across a whole file may not.
Bad Names
Six Names That Fail Readers
Here are names that fail, and why. x2 carries no meaning at all, so the reader must trace every use. Adjusted price says what it holds. Temp is true of almost any variable, and it tends to survive long after the value stopped being temporary. Num names the kind of thing, not the thing. Every number is a number. Which one is this? Retry count tells you. Calc val usr inp is abbreviated past recognition. Saving keystrokes costs every future reader a decoding step. Flag doesn't say which answer means what. Boolean names should read as a question, like is complete. And total using loop describes the technique, so if you change the technique, the name becomes a lie.
Comment Syntax
Line Comments and Block Comments
C++ has two ways to write a comment. Both are removed before translation, and neither affects the program. A line comment starts with two slashes, and runs to the end of that line. A block comment begins with slash star, continues across as many lines as you like, and ends with star slash. Line comments are used for almost everything: notes beside a line, short explanations, and disabling code while you test. Block comments suit longer passages, like a file's header.
Common Trap
Block Comments Don't Nest
One trap is worth knowing now: block comments don't nest. Wrap a region in slash star to disable it. If it already holds a block comment, the first star slash inside ends yours early. Everything after it becomes live code again, and the build fails on your stray star slash. Wrapping lines in line comments instead is always safe, and every editor can do it to a selection in one action.
Comment Quality
Explain Why, Not What
The most common mistake is commenting what the code does. The code already says that, more reliably, because code can't fall out of date. So before writing a comment, ask: does it repeat the code? If not, write it. It explains why. If it does, ask whether a better name would remove the need. If so, rename instead. The comment was a symptom. If not, delete it. Add one to attempts isn't worth writing. One attempt per prompt, even if the value was rejected, is. Set rate to point one eight just restates the line. Eighteen percent is the combined rate in force from April, explains a number nobody could otherwise trace. And a comment that no longer matches its line is worse than none. A reader who trusts it is misled, and one who catches it distrusts every comment in the file.
File Header
Four Fixed Lines and Optional Notes
Every file you submit opens with a short header block, telling a reader what they're looking at before they read any code. Four lines are fixed: the file's name, its purpose in one sentence, who wrote it, and when. The notes line is optional. It's for anything a reader would otherwise discover the hard way, like an assumption, or a deliberate limitation. Keep it to a few lines. Its value is that it can be scanned in seconds, and a long one isn't scanned at all.
Spacing Rules
Spaces, Blank Lines, and Line Length
Within a line, spacing groups the parts of an expression the way the compiler does. Between lines, blank lines mark where one stage of the work ends. Put a space on each side of a binary operator, so total equals price times quantity plus fee is easy to read. A space after each comma, and none before. A space after a keyword like if, but none after a function name. No space inside square brackets, and one declaration per line. Lines stop at one hundred characters. When an expression won't fit, break it before an operator, and indent the continuation one level. Every serious editor can do most of this for you. Configure it once: four-space indentation, spaces instead of tabs, and a marker at column one hundred.
Quick Check
Mixed Indentation Versus Three Spaces
Quick check. One file indents by four spaces in places and two in others. Another indents by three spaces everywhere. Which is harder to read? Pause and decide. The mixed one. Three is an unusual choice, but a reader adjusts to it once. Mixed indentation makes every line a new question. Consistency does more work than any particular choice. A file that switches styles is harder to read than one that sticks to the weaker style.
Submission Checklist
How Your Work Is Read
Work you hand in is read against this checklist, in roughly the order a reader notices things. A header block that's present and accurate. Four spaces per level, spaces only. Braces aligned, and always present. Names in the four forms, with leftover working names like temp and x renamed. Comments that explain reasons. No disabled code, and no contradicting comments. Lines under one hundred characters. One statement and one declaration per line. Consistent spacing, and blank lines between stages. These conventions feel like overhead while programs are twenty lines long. Every one was invented by people whose programs weren't. Adopt them while the stakes are low. Layout isn't decoration applied at the end. It's written as you go.
Key Takeaways
Readable Code and Consistency Summary
To summarize. Whitespace, names and comments are invisible to the compiler. They exist for the people who read your code, including you. Use four spaces per level, aligned braces on their own lines, braces always, and one statement per line. Let names carry their own explanation, and use comments to explain why, not what. And above all, be consistent. Consistency does more work than any particular choice.
About C++ Programming at UPI Study
C++ Programming (Computer Science 242) is a self-paced online course of 84 video lessons in 11 chapters, from your first program to decisions, loops, arrays, functions, classes, files, pointers and inheritance. It carries a NCCRS credit recommendation for 3 semester credits.
Every lesson transcript is free on pages like this one, and the videos are free with a free UPI Study account. Enrolling adds a practice quiz after each lesson, the graded work and final exam that earn the credit, lifetime access, and an official transcript on completion. UPI Study has helped over 130,000 students with college credits. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.
Enroll now → Course details Download the syllabus Every course with PRO →
Why take it here
Why students take C++ Programming with UPI Study
Where the credit goes
Universities that work with NCCRS
C++ Programming carries a NCCRS credit recommendation. These universities work with NCCRS; some are UPI Study's signed partners. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.
Thomas Edison State UniversitySigned partner
University of the PeopleSigned partner
Charter Oak State CollegeSigned partner
Strayer UniversitySigned partner
Columbia Southern UniversitySigned partner
Indiana TechSigned partner
Penn StateWorks with NCCRS
Southern New Hampshire UniversityWorks with NCCRS
SUNYWorks with NCCRS
+many more cooperating universitiesFind my college →Find my college → Not listed? Ask Athena in the corner of this page, or book a 15-minute call.
FAQ
Questions students ask us
About Professional Habits: Readability Standards
Why should I put braces around a one-statement if body in C++?
What are the naming conventions for variables, functions, constants, and types in this C++ course?
When should I write a comment in C++ code, and when should I skip it?
What spacing and line-length rules should I follow when writing C++?
About the C++ Programming course
How many college credits is C++ Programming?
How much does C++ Programming cost and what is included?
Which universities accept UPI Study credits?
How long does C++ Programming take?
How are the exams done?
How do my credits reach my college?
Ready for the full course? Earn 3 credits in C++ Programming.
84 video lessons, a quiz after each one, and the graded work that earns the credit. Recommended for credit by NCCRS.
3 credits · NCCRSEnroll →