1. Communicating in Code: Layout and Style
Programming Studio, Fall 2017
Tanzir Ahmed
Note: several examples in this lecture taken from The Practice of Programming by Kernighan and Pike

2. Layout and Style Like naming, the goal is to communicate
Again like naming, sometimes conventions are in place
Adhering to the convention in place will usually lead to more readable code than using your own “better” convention
Goal of layout and style is to increase clarity.

3. Fundamental Theorem of Formatting
Good visual layout shows the logical structure of the program.
Studies show that organization is as important to understanding as the “details”

4. White Space Used to indicate logical grouping
Spacing between characters
Indentation
Blank lines

5. Line Breaks Use blank lines to separate different sections of code
Separate concepts should be reflected by separate blocks of code
Should usually comment start of each “block”
Put blank lines between functions/methods.

6. Indentation Can clarify structure, especially in odd cases
Studies show that 2-4 space indentation works best.
More indentation might “appear” better, but is not
Now, usually editors provide automatically
But, variations for some statements:
switch/case
if/elseif
Brace conventions differ, but be consistent

7. Example Brace Conventions
while (something) {
blahblahblah }
while (something) {
blahblahblah }
while (something) {
blahblahblah }
while (something) {
blahblahblah }

8. Parentheses Parentheses can resolve ambiguity
Particularly important since order of operations can be problematic
Better to use more parentheses than you think you need
Coupled with white space, can more quickly highlight the grouping/ordering of operations
leap_year = y % 4 == 0 && y % 100 != 0 || y % 400 == 0;

9. Parentheses Parentheses can resolve ambiguity
Particularly important since order of operations can be problematic
Better to use more parentheses than you think you need
Coupled with white space, can more quickly highlight the grouping/ordering of operations
leap_year = y % 4 == 0 && y % 100 != 0 || y % 400 == 0;
leap_year = ((y%4 == 0) && (y%100 != 0)) || (y%400 == 0);

10. Optional Braces Like parentheses, use more(??) braces than you need
One-statement operation often becomes more, later
if (a > b)
max = a;

11. Optional Braces Like parentheses, use more braces than you need
One-statement operation often becomes more, later
if (a > b)
max = a;
cout << “Set a new maximum.” << endl;

12. Optional Braces Like parentheses, use more braces than you need
One-statement operation often becomes more, later
if (a > b) {
max = a; }

13. Braces Like parentheses, use more braces than you need.
One-statement operation often becomes more, later.
if (a > b) {
max = a;
cout << “Set a new maximum.” << endl; }

14. Avoiding Complex Expressions
Goal is not to write most concise and clever code
Break up expressions to make them clearer
The “?” operator can be especially problematic
*x += (*xp=(2*k < (n-m) ? c[k+1] : d[k--]));
if (2*k < n-m)
*xp = c[k+1];
else
*xp = d[k--];
*x += *xp;

15. Avoiding Complex Expressions
Goal is not to write most concise and clever code
Break up expressions to make them clearer
The “?” operator can be especially problematic
*x += (*xp=(2*k < (n-m) ? c[k+1] : d[k--]));
if (2*k < n-m) {
*xp = c[k+1];
} else {
*xp = d[k--]; }
*x += *xp;

16. Use “Natural Form” for Expressions
State conditional tests positively
if (!(z>=0) && !(z<a))
if ((z<0) && (z>=a))
This can vary if the way it’s expressed better matches the underlying algorithm

17. Use “idomatic” forms
There are “common” ways of expressing certain things.
e.g. Use a for loop appropriately – loop control in the for statement, and other operations outside
for (i=0;i<n;i++)
a[i] = 0.0;
for (i=0;i<n;a[i++]=0.0);
for (i=0;i<n;) {
i++ }

18. Idiomatic forms Use if-elseif-else form whenever possible
Alternatives are more difficult to understand
if (cond1) {
dothis1();
} else {
if (cond2) {
dothis2();
if (cond3) {
dothis3();
dothis4(); }
if (cond1) { dothis1(); } else if (cond2) { dothis2(); } else if (cond3) { dothis3(); } else { dothis4(); }

19. If statements
Read so that you look for the “true” case rather than a “stack” of else cases
if (a > 3) {
if (b < 12) {
while (!EOF(f)) {
dothis(); }
} else {
cerr << “Error 2” << endl;
cerr << “Error 1” << endl;
if (a <= 3) {
cerr << “Error 1” << endl;
} else if (b >= 12) {
cerr << “Error 2” << endl;
} else {
while (!EOF(f)) {
dothis(); }

20. Avoid Magic Numbers The constant values that we use in our programs
Rule of thumb: any number other than 0 or 1 is probably a “magic number”
Can lead to tremendous debugging problems when these numbers are changed
One change is out-of-sync with others
Instead, define constants, or variables, to give names to those numbers.
int a = 1 – a; // alternating between 1 and 0 int a = rand ()% ; //random num. in range [1,100]
No need to have variables replacing “1”

21. Avoid Magic Numbers
Rule of thumb: any number other than 0 or 1 is probably a “magic number”
Can lead to tremendous debugging problems when these numbers are changed
Instead, define constants, or variables, to give names to those numbers.
Even better
const int WINHEIGHT = 400;
windowPosY = WINHEIGHT-y
windowPosY = 400-y; OK OR
int WINHEIGHT = 400;
windowPosY = WINHEIGHT-y
#define WINHEIGHT 400 …
windowPosY = WINHEIGHT-y

22. Layout for Control Structures
Put control in one line when possible
Single indentation level for what it affects
xxxxxx
xxxxx
Group each part of a complicated condition on its own line
Same idea as before, break-down whenever necessary

23. Layout of Individual Statements
White space can improve readability
Spaces after commas
Write it in the same way you write English
EvaluateEmployee(Name.First,EmployeeID,Date.Start,Da te.End);
EvaluateEmployee (Name.First, EmployeeID, Date.Start, Date.End);
Spaces between parts of conditions
if (((a<b)||(c>d))&&((a+b)<(c-d))&&((c-d)>2))
If ((a<b) || (c>d)) && ((a+b)<(c-d)) && ((c-d)>2))

24. Layout of Individual Statements
White space can improve readability
Spaces after commas
EvaluateEmployee(Name.First,EmployeeID,Date.Start,Date.End);
EvaluateEmployee (Name.First, EmployeeID, Date.Start, Date.End);
Spaces between parts of conditions
if (((a<b)||(c>d))&&((a+b)<(c-d))&&((c-d)>2))
if (((a<b) || (c>d)) && ((a+b)<(c-d)) && ((c-d)>2))
if (((a<b) || (c>d)) &&
((a+b) < (c-d)) &&
((c-d) > 2) )

25. Layout of Individual Statements
Line up related definitions or assignments
StudentName = ProcessInputName();
StudentID = ProcessInputID();
StudentHometown = ProcessInputName();
There is a big problem with this, though!

26. Layout of Individual Statements
Line up related definitions or assignments
Don’t use more than one statement per line.
Likewise, define only one variable per line.
Exception: when defining sets of variables or writing statements with same purpose
x = ray.computehits(); nhits = x.size(); // unrelated
x = ray.computehits(); //better
nhits = x.size();
int i; float[3] newpoint; //dissimilar data types
int i;
float[3] newpoint;
point vertex1, vertex2, vertex3; // variables with similar purposes
a[i]=b[i]=c[i]=0.0;

27. Layout of Individual Statements
Line up related definitions or assignments
Don’t use more than one statement per line.
Avoid side-effects (such as including the ++ operator when doing something else).
Try to write in separate statements.
x[i++] = 0;
x[i] = 0;
i++;

28. When a Line is Too Long
Make it clear that the previous line is not ending (e.g. end with an operator)
Keep related parts of the line together (don’t break single thought across line)
Use indentation to highlight that there’s a continuation
Make it easy to find the end of the continued line

29. When a line is too long Clear continuation Indentation
retirementFunds=AmtAfterTax(Compound(checkingBalance,checkingRate, yearsleft)+Compound(savingsBalance,savingsRat,yearsleft)+Compound( mutualFundBalance,fundRate,yearsleft),taxRate)+Compound(rothiraBalance ,fundRate,yearsleft); retirementFunds = AmtAfterTax ( Compound (checkingBalance, checkingRate, yearsleft) + Compound (savingsBalance, savingsRat, yearsleft) + Compound (mutualFundBalance, fundRate, yearsleft), taxRate) + Compound(rothiraBalance, fundRate, yearsleft);
Clear continuation
Indentation

30. Layout of Routines Use standard indentation approach for arguments
Use blank lines to separate parts of routines or blocks of common actions
Slightly different idea/purpose
Just like an essay where Paragraphs are used to separate ideas
Use comments (will return to it later) to identify major breaks in conceptual flow
Completely different idea

31. Layout of Files
Clearly separate (multiple line breaks) different routines in the same file
Don’t want to accidentally “merge” or “break” individual routines
Also helps easy navigation
Sequence functions inside files in a logical manner
Functions in a .cpp files are written in the same order as in the .h files
Or, in alphabetical order
Or, Constructor, accessor, destructor, other – in this order
Again, whatever you choose, be consistent