Show Lecture.CodingStyle as a slide show.

CS253 Coding Style

:

Communication in English

• This is not an English class. I don’t mind if your statements, email, or chats contain a few mistakes, or non-standard constructs. As long as the meaning gets across, then the message has served its purpose.
• On the other hand, if your spelling or grammar is so bad that I can’t understand what you mean, then the communication has failed.
• My point is: good enough is good enough, but if you paa know ɘ10shun atawl 2 ur englech, thet g3tz n teh whey uf komune a cashun.

Communication in Programming

• This is a programming class.
• Your program is a message to the compiler AND human beings.
• Yes, your message has two recipients. They both matter.
• CS students tend to give the compiler all their attention; they fail otherwise.
• The human might be who takes over your code after you move to another project. It might be somebody trying to fix a bug, or to add a feature, years later. It might be you, desperately trying to remember what this code does.
• We do a poor job of teaching CS students that readability matters, because it’s difficult.

Style Conventions

• I will now present the C++ coding style that I prefer.
• There is a lot of opinion here. It’s my class!
• When you work for someone else, follow their house style until you are in charge.
• You will not be graded on whether you follow these conventions.
• However, you should.

Names

• A person’s name isn’t arbitrary letters—it conveys meaning. In some cultures, certain names imply gender, though times be changin’. This is sometimes enforced by law, but usually by social pressure.
• In C++, names have meaning, by convention. That means that the compiler doesn’t enforce this—the community does.
• Conform, or risk confusing other programmers.

Names

variables, methods, functions

start with a…z, continue with a…z, A…Z, 0…9 or _: foobar, foo_bar, fooBar

user-defined classes

start with A…Z, continue with a…z, A…Z, 0…9 or _: Foobar, FooBar

constants via constexpr or #define

start with A…Z, continue with A…Z, 0…9 or _: FOOBAR, FOO_BAR

Beginners love to make their variables ALL_UPPER_CASE, because it looks more computery. This confuses experienced coders.

Names

• Use i and j in for loops.
• Call a double d, a pointer p, a reference r, if you don’t have a better name.
• Use small names for small scope: just a few lines, a small if statement or while loop.
• Use larger names for larger scope: a global variable, an entire function, function names, data members.

Spacing

• Always have spaces after keywords.
• Put a space before an opening brace.

if (3 < 4) {
    count--;
    cout << "Hooray!\n";
}
else {
    cout << "Math is broken\n";
}

Spacing

• Use spaces around =:

int x = 2+2;

• Use a space after a comma:

int x, y, z;
foo(x, y+z)

• Use spaces as pseudo-parentheses, to group parts of an expression. Otherwise, spaces around operators are optional.

hypot = sqrt(x*x + y*y);

Braces

• Vertical screen space is precious—don’t waste a line on {.
• Line up the closing } with the if, for, or while.
• Avoid { } if they’re not needed.

if (3 < 4) {
    count--;
    cout << "Hooray!\n";
}
if (5>6)
    cerr << "oops!\n";
for (int i=0; i<10; i++) {
    cout << "i=" << i << "\n";
    do_other_thing();
}

Comments

• Only use use /* … */ comments to document an unused argument.
• Put a block comment before each non-trivial function.
• Add comments after lines that need them. Line up comments, or put two spaces between the semicolon and the //.

// The destroy function takes a size and eliminates
// all widgets of that size.  The hint argument will be
// implemented someday.
void destroy(int size, string /* hint */) {
    if (size <= 0)  // nothing can be that size
        return;
    alpha(size);            // explain why
    beta(size);             // we are calling
    gamma(size);            // all these functions!
}

Indentation

• Indent the bodies of if, else, for, while, do, switch, try, catch, class, struct, union, functions, #if, #ifdef, #ifndef, #elif, and #else.
• Indent four spaces, with a half-indent for case or default, and public, private, protected sections in a class.

Tabs

• Tab stops are every eight columns, and you can’t change that. Sure, you can tell your editor to think that a tab character means every three columns, but you can’t make everybody else do that, so your source files look terrible to others.
• It’s fine to tell your editor that you pressing the tab key means to go forward four spaces, as long as the file conforms to the tab-every-eight-columns standard.
• To tell if you got tabs right: cat yourfile.cc in a terminal. If it looks bad there, then it will look bad to others.

Now, not Later

• Do this as you write the code, not later. This isn’t something that you add on at the end to make it pretty for turning in.
• Why write ugly code, then go back and re-write it to make it pretty? Why write your code twice for no reason?
• You are the person who has to deal with your code the most, as you write it. Why should you have to put up with variables named m, methods named doit, and no indentation? Why torture yourself? Coding is hard enough without making it harder.
• That would be like carrying your winter coat during a snowstorm. Put it on! What are you saving it for?