------------------------------------------------------------------------------
Style Checker FAQ
------------------
written May 2004
by Seth Grover
1. What is the style checker ?
2. What isn't the style checker?
3. How do I use the style checker?
4. What is good style?
5. What does/doesn't the style checker check for?
6. What will happen if I ignore the style checker?
7. I've found a bug -- what do I do?
8. Who wrote the style checker?
The style checker is a script designed to test C++ and Java source
code for adherence to standard coding style guidelines. Students
use it to check their code for style before submitting homework
assignments to their instructors. Instructors use it for grading
purposes.
The style checker isn't designed to test your code for
correctness or elegance. In other words, it's not going to tell
you if you used the right algorithm, if your code is
object-oriented enough, or if you're using duplicate code, just
like Word's spelling checker won't tell you if your English paper
has a well-developed thesis. Also, it's not a compiler -- it won't
catch syntax errors or other problem-causing mistakes like
for (j = 0; j < 5; i++).
It won't necessarily help you write good code, although it can
help you write good-looking code.
The style checker is not a style fixer. It was intended this way
to help coders get in the habit of programming with good style,
not to force code with bad style into conformity. By the end of
the semester, most CS 165 students' code passes the style checker
on the first try. When the style checker gripes at you for
incorrectly indenting 1345 lines that you need to fix (one at a
time), the smart coder quickly learns to do it right the first time.
1. Open a terminal window and navigate to the directory
containing your source code file (with a .cpp or .java
extension).
2. Type:
sc nameOfFileToCheck.cpp (substituting your file name, of course)
3. You will see the style checker run through its checklist,
and then you will be presented with a summary of the style
errors, if any, and a list of variable, class, and
subroutine names and the lines on which they are
defined/declared.
4. Correct the errors in your code, and then run the style
checker again to make sure you corrected everything.
Like any Unix command line utility, the style checker's output can
be redirected using the pipe (|) or redirection (>) operators.
This can be useful, especially when you have a lot of style errors
and you don't want to have to scroll through 2000 lines generated
by the style checker.
For example, to redirect the style checker's results to a file
called styleErrors.txt:
sc myProgram.cpp > styleErrors.txt
Or, to view only the output concerning the use of tabs instead of
spaces:
sc myProgram.cpp | grep "tabs"
The style checker is programmed to test conformity to the style
rules of the Computer Science and Engineering Department at
BYU-Idaho. A good summary of these guidelines can be found on
Brother Twitchell's web site (emp.byui.edu/twitchellk/style.html).
Admittedly, the whole world does not agree on all matters of
coding style. It's very likely that many students (and even
instructors) here at BYU-I prefer slightly different styles.
Programming environments in the "real world" will compel you to
conform to organization-wide coding style standards. The style
checker is no different and prepares students for the field by
making them adaptable.
- Introductory comment blocks.
What it does:
Requires that an introductory program comment block be the
first thing in your code. Checks for this block's existence,
checks for correct indentation of the block and its
contents, and checks to make sure each required element is
present in the block. A template for this block can be found
on jordan as /home/twitchellk/examples/style/cpp/program.txt.
What it doesn't do:
Does not check for appropriateness or completeness of your
comments. A brief summary of the program and what it does
should be included by the author. Programs will be graded
according to how meaningful these comments are, and that
must be checked manually.
- Subroutines commented.
What it does:
Checks to make sure each function is preceded by a comment
block formatted according to the template found in Brother
Twitchell's directory as
/home/twitchellk/examples/style/cpp/function.txt
Also, checks to make sure each class definition is
preceded by a similar comment block (see class.txt in the same
directory).
What it doesn't do:
Does not check whether comments are meaningful or complete.
- Variables declared on their own line.
What it does:
Checks to make sure all variables are declared on their own line.
- Correct use of case.
What it does:
Checks the case of the first letter of variable, class, and
subroutine identifiers. Variable and subroutine names should
begin with a lowercase character. Classes should begin with
an uppercase character. Also, creates a list of identifiers
(variables, classes, and subroutines) for the user to check.
What it doesn't do:
If an identifier consists of more than one word, the words
should be joined together, and each word after the first
should begin with an uppercase letter (eg., thisIsAVariable). The
style checker does not check correct case of anything except
the first letter of identifiers. The style checker does list the
identifiers after the summary of style errors. The user is
then required to check to make sure correct case is used
in naming each identifier.
- No underscores.
What it does:
Checks to make sure identifiers are not used in naming
non-constant identifiers. Underscores in constant names are
allowed, such as in this declaration:
const int THIS_IS_A_CONSTANT;
The style checker will not complain about the use of most
valid functions with underscores in the name such as c_str()
and find_first_of().
What it doesn't do:
The list of valid identifiers with underscores is not
comprehensive. You may find yourself using a function from
an included library that causes the style checker to
complain. When this happens, don't be alarmed. You
(probably) won't be docked for it. You can report the
function name to Brother Twitchell to have it added to the
valid list.
- White space between operators.
What it does:
Checks to make sure all operators and operands are separated
by at least one space. Unary operators such as - (as in y = -x;)
and ++ are not included in this rule.
- White space before subroutines.
What it does:
Checks to make sure there is at least one blank line before
each subroutine's (or class') comment block begins.
- Curly braces on their own line.
What it does:
Checks to see if each curly brace designating a block of
code is on its own line. For example,
wrong: right:
while (x < 3) { while (x < 3)
code... {
} code...
}
Curly braces used in statments like "int theArray[3] = {3, 2, 1};"
are considered valid.
What it doesn't do:
Does not check to make sure your open/closed curly braces
match up in number (since that's not really a style issue).
- Lines under 80 characters.
What it does:
Checks to make sure all lines are less than 80 characters in
length (including code, comments, and "blank" lines
consisting of only spaces).
- Correct spelling.
What it does:
Checks your comments to see if any common words are spelled
incorrectly.
What it doesn't do:
It probably won't catch things such as your name, place
names, or uncommon words you use in your comments. If you
misspell your own name or "Idaho" or something like, that
you'll probably be docked for it.
- No unused code.
What it does:
Looks for possible commented-out code. A line in comments is
flagged as unused code if and only if:
1. It ends in a ';'.
2. It contains a variable, function, class, or structure
name.
3. It contains an operator in it (other than a '*' at the
start of the line).
Don't worry if you have something valid in your comments
which causes the style checker to suggest you have possible
unused code. There may be valid situations in which you
might want to include something like that for explanatory
purposes in commenting. If you're sure it's not
commented-out code that shouldn't really be there, don't
fret too much over the style checker's warning in this area.
- Space after key words.
What it does:
Checks to make sure key words such as if, for, and return (to
name just a few) are followed by a space.
wrong: if(x == 1)
right: if (x == 1)
- No tabs.
What it does:
Flags the presence of any tab character in your program.
Tabs are interpreted differently by different editors. Your
code may look fine in one editor, but a different editor may
translate it differently, making the code all but illegible
to someone trying to read it. It is a commonly accepted
coding standard to use spaces instead of tabs.
What it doesn't do:
Replace all tabs with spaces in your code. If you want an
easy way to do this, you can write a simple Perl script to
take care of the substitutions for you. Also, most editors
in the lab (emacs, vi, and gedit) can be configured to use
spaces instead of tabs for indenting purposes.
- Consistent indentation.
What it does:
Checks your code for consistent indentation. BYU-I coding
standards specify an indentation of three spaces for all
blocks of code. Multi-line statements should have extra
lines indented at least three spaces past the first line of
the statement, as in:
cout << "hello "
<< "and "
<< "goodbye";
cout << "hello "
<< "and "
<< "goodbye";
Both of the above examples show correct indentation.
After using the style checker a few times, you'll begin to
get a feel for the indentation style required.
What it doesn't do:
Breaking other style rules can confuse the indentation
portion of the style checker. For example, failing to put
the curly brace of a do/while statement on its own line
(as in 'do {') may cause the style checker to report indentation
errors incorrectly, since the style checker uses the curly brace
on its own line to determine where indented blocks should
start. If the style checker becomes confused, it will report
the error in a less specific way than usual. As you fix the
other style errors, the indentation checker becomes very
accurate since it checks your source code recursively.
- Other things the style checker doesn't do:
The style checker does not check your code for the presence
of in-code comments that should be included to describe program
flow and explain what is going on to others reading the code.
The style checker does not check comments to make sure they
are appropriate, meaningful, or complete.
The style checker does not check check identifier names for
appropriateness. For example, a variable named sum tells us we are
adding something; naming it sumOfSquares tells us specifically what
we are adding. Naming it x or cheeseSandwich doesn't tell us
anything (and you'll probably be docked for it).
That depends on the nature of the error reported as well as the
nature of your instructor. Some style "errors" reported by the
style checker shouldn't be cause for alarm. For example, the style
checker may complain about a spelling error if you include your
name somewhere in the comments, or may gripe when you invoke some
subroutine with underscores in its name from a standard library.
Often you can disregard warnings like this. Also, some instructors
weigh style more heavily in their grading criteria. You may want
to get to know what's expected of you regarding style before you
pull your hair out over conforming to the style checker.
If you're sure you've found a bug in the style checker, report
it to Brother Twitchell who will review the problem and pass the
information on to the student in charge of maintaining the style
checker if necessary.
Work on the style checker began in the summer of 2003 by Lynn
Mendenhall. Clay Allen continued maintenance and development of
the style checker through the fall of 2003, followed by Seth
Grover.
------------------------------------------------------------------------------
written by Seth Grover (gro00002@byui.edu)
May, 2004
Style Checker FAQ
------------------
written May 2004
by Seth Grover
1. What is the style checker ?
2. What isn't the style checker?
3. How do I use the style checker?
4. What is good style?
5. What does/doesn't the style checker check for?
6. What will happen if I ignore the style checker?
7. I've found a bug -- what do I do?
8. Who wrote the style checker?
1. What is the style checker?
The style checker is a script designed to test C++ and Java source
code for adherence to standard coding style guidelines. Students
use it to check their code for style before submitting homework
assignments to their instructors. Instructors use it for grading
purposes.
2. What isn't the style checker?
The style checker isn't designed to test your code for
correctness or elegance. In other words, it's not going to tell
you if you used the right algorithm, if your code is
object-oriented enough, or if you're using duplicate code, just
like Word's spelling checker won't tell you if your English paper
has a well-developed thesis. Also, it's not a compiler -- it won't
catch syntax errors or other problem-causing mistakes like
for (j = 0; j < 5; i++).
It won't necessarily help you write good code, although it can
help you write good-looking code.
The style checker is not a style fixer. It was intended this way
to help coders get in the habit of programming with good style,
not to force code with bad style into conformity. By the end of
the semester, most CS 165 students' code passes the style checker
on the first try. When the style checker gripes at you for
incorrectly indenting 1345 lines that you need to fix (one at a
time), the smart coder quickly learns to do it right the first time.
3. How do I use the style checker?
1. Open a terminal window and navigate to the directory
containing your source code file (with a .cpp or .java
extension).
2. Type:
sc nameOfFileToCheck.cpp (substituting your file name, of course)
3. You will see the style checker run through its checklist,
and then you will be presented with a summary of the style
errors, if any, and a list of variable, class, and
subroutine names and the lines on which they are
defined/declared.
4. Correct the errors in your code, and then run the style
checker again to make sure you corrected everything.
Like any Unix command line utility, the style checker's output can
be redirected using the pipe (|) or redirection (>) operators.
This can be useful, especially when you have a lot of style errors
and you don't want to have to scroll through 2000 lines generated
by the style checker.
For example, to redirect the style checker's results to a file
called styleErrors.txt:
sc myProgram.cpp > styleErrors.txt
Or, to view only the output concerning the use of tabs instead of
spaces:
sc myProgram.cpp | grep "tabs"
4. What is good style?
The style checker is programmed to test conformity to the style
rules of the Computer Science and Engineering Department at
BYU-Idaho. A good summary of these guidelines can be found on
Brother Twitchell's web site (emp.byui.edu/twitchellk/style.html).
Admittedly, the whole world does not agree on all matters of
coding style. It's very likely that many students (and even
instructors) here at BYU-I prefer slightly different styles.
Programming environments in the "real world" will compel you to
conform to organization-wide coding style standards. The style
checker is no different and prepares students for the field by
making them adaptable.
5. What does/doesn't the style checker check for?
- Introductory comment blocks.
What it does:
Requires that an introductory program comment block be the
first thing in your code. Checks for this block's existence,
checks for correct indentation of the block and its
contents, and checks to make sure each required element is
present in the block. A template for this block can be found
on jordan as /home/twitchellk/examples/style/cpp/program.txt.
What it doesn't do:
Does not check for appropriateness or completeness of your
comments. A brief summary of the program and what it does
should be included by the author. Programs will be graded
according to how meaningful these comments are, and that
must be checked manually.
- Subroutines commented.
What it does:
Checks to make sure each function is preceded by a comment
block formatted according to the template found in Brother
Twitchell's directory as
/home/twitchellk/examples/style/cpp/function.txt
Also, checks to make sure each class definition is
preceded by a similar comment block (see class.txt in the same
directory).
What it doesn't do:
Does not check whether comments are meaningful or complete.
- Variables declared on their own line.
What it does:
Checks to make sure all variables are declared on their own line.
- Correct use of case.
What it does:
Checks the case of the first letter of variable, class, and
subroutine identifiers. Variable and subroutine names should
begin with a lowercase character. Classes should begin with
an uppercase character. Also, creates a list of identifiers
(variables, classes, and subroutines) for the user to check.
What it doesn't do:
If an identifier consists of more than one word, the words
should be joined together, and each word after the first
should begin with an uppercase letter (eg., thisIsAVariable). The
style checker does not check correct case of anything except
the first letter of identifiers. The style checker does list the
identifiers after the summary of style errors. The user is
then required to check to make sure correct case is used
in naming each identifier.
- No underscores.
What it does:
Checks to make sure identifiers are not used in naming
non-constant identifiers. Underscores in constant names are
allowed, such as in this declaration:
const int THIS_IS_A_CONSTANT;
The style checker will not complain about the use of most
valid functions with underscores in the name such as c_str()
and find_first_of().
What it doesn't do:
The list of valid identifiers with underscores is not
comprehensive. You may find yourself using a function from
an included library that causes the style checker to
complain. When this happens, don't be alarmed. You
(probably) won't be docked for it. You can report the
function name to Brother Twitchell to have it added to the
valid list.
- White space between operators.
What it does:
Checks to make sure all operators and operands are separated
by at least one space. Unary operators such as - (as in y = -x;)
and ++ are not included in this rule.
- White space before subroutines.
What it does:
Checks to make sure there is at least one blank line before
each subroutine's (or class') comment block begins.
- Curly braces on their own line.
What it does:
Checks to see if each curly brace designating a block of
code is on its own line. For example,
wrong: right:
while (x < 3) { while (x < 3)
code... {
} code...
}
Curly braces used in statments like "int theArray[3] = {3, 2, 1};"
are considered valid.
What it doesn't do:
Does not check to make sure your open/closed curly braces
match up in number (since that's not really a style issue).
- Lines under 80 characters.
What it does:
Checks to make sure all lines are less than 80 characters in
length (including code, comments, and "blank" lines
consisting of only spaces).
- Correct spelling.
What it does:
Checks your comments to see if any common words are spelled
incorrectly.
What it doesn't do:
It probably won't catch things such as your name, place
names, or uncommon words you use in your comments. If you
misspell your own name or "Idaho" or something like, that
you'll probably be docked for it.
- No unused code.
What it does:
Looks for possible commented-out code. A line in comments is
flagged as unused code if and only if:
1. It ends in a ';'.
2. It contains a variable, function, class, or structure
name.
3. It contains an operator in it (other than a '*' at the
start of the line).
Don't worry if you have something valid in your comments
which causes the style checker to suggest you have possible
unused code. There may be valid situations in which you
might want to include something like that for explanatory
purposes in commenting. If you're sure it's not
commented-out code that shouldn't really be there, don't
fret too much over the style checker's warning in this area.
- Space after key words.
What it does:
Checks to make sure key words such as if, for, and return (to
name just a few) are followed by a space.
wrong: if(x == 1)
right: if (x == 1)
- No tabs.
What it does:
Flags the presence of any tab character in your program.
Tabs are interpreted differently by different editors. Your
code may look fine in one editor, but a different editor may
translate it differently, making the code all but illegible
to someone trying to read it. It is a commonly accepted
coding standard to use spaces instead of tabs.
What it doesn't do:
Replace all tabs with spaces in your code. If you want an
easy way to do this, you can write a simple Perl script to
take care of the substitutions for you. Also, most editors
in the lab (emacs, vi, and gedit) can be configured to use
spaces instead of tabs for indenting purposes.
- Consistent indentation.
What it does:
Checks your code for consistent indentation. BYU-I coding
standards specify an indentation of three spaces for all
blocks of code. Multi-line statements should have extra
lines indented at least three spaces past the first line of
the statement, as in:
cout << "hello "
<< "and "
<< "goodbye";
cout << "hello "
<< "and "
<< "goodbye";
Both of the above examples show correct indentation.
After using the style checker a few times, you'll begin to
get a feel for the indentation style required.
What it doesn't do:
Breaking other style rules can confuse the indentation
portion of the style checker. For example, failing to put
the curly brace of a do/while statement on its own line
(as in 'do {') may cause the style checker to report indentation
errors incorrectly, since the style checker uses the curly brace
on its own line to determine where indented blocks should
start. If the style checker becomes confused, it will report
the error in a less specific way than usual. As you fix the
other style errors, the indentation checker becomes very
accurate since it checks your source code recursively.
- Other things the style checker doesn't do:
The style checker does not check your code for the presence
of in-code comments that should be included to describe program
flow and explain what is going on to others reading the code.
The style checker does not check comments to make sure they
are appropriate, meaningful, or complete.
The style checker does not check check identifier names for
appropriateness. For example, a variable named sum tells us we are
adding something; naming it sumOfSquares tells us specifically what
we are adding. Naming it x or cheeseSandwich doesn't tell us
anything (and you'll probably be docked for it).
6. What will happen if I ignore the style checker?
That depends on the nature of the error reported as well as the
nature of your instructor. Some style "errors" reported by the
style checker shouldn't be cause for alarm. For example, the style
checker may complain about a spelling error if you include your
name somewhere in the comments, or may gripe when you invoke some
subroutine with underscores in its name from a standard library.
Often you can disregard warnings like this. Also, some instructors
weigh style more heavily in their grading criteria. You may want
to get to know what's expected of you regarding style before you
pull your hair out over conforming to the style checker.
7. I've found a bug - what do I do?
If you're sure you've found a bug in the style checker, report
it to Brother Twitchell who will review the problem and pass the
information on to the student in charge of maintaining the style
checker if necessary.
8. Who wrote the style checker?
Work on the style checker began in the summer of 2003 by Lynn
Mendenhall. Clay Allen continued maintenance and development of
the style checker through the fall of 2003, followed by Seth
Grover.
------------------------------------------------------------------------------
written by Seth Grover (gro00002@byui.edu)
May, 2004