Formatting, Spelling, and Documentation#

Formatting, spelling, and documentation tools can improve the presentation of a program. They do not replace the assignment instructions or the course programming standards.

The current course syllabus, assignment instructions, programming standards, and applicable CSN or college policies take precedence over anything on this website.

astyle#

astyle can reformat C++ source code. On Bellagio, astyle is preconfigured to follow the general programming guidelines, including broken braces, space-based indentation, spaces around operators, and other common formatting rules.

For normal course use, run:

astyle main.cpp

You can replace main.cpp with the name of the source file you want to format. The command may change many lines at once, so review the result before submitting.

Students may use a particular style, such as Allman, if they use it consistently within their code. If you choose to specify a style, use the option intentionally:

astyle --style=allman main.cpp

The style you use must still follow the assignment instructions. Consistency within your program is the main requirement.

Before using an automatic formatter:

• Save your work.
• Compile the program.
• Format one file.
• Review the changes.
• Compile again.

Do not use a formatter to avoid understanding the course standards.

aspell#

aspell checks spelling. It is useful for comments, documentation, and text files. It may not understand every programming term or identifier.

Check a C++ source file:

aspell --mode=ccpp check main.cpp

Check a Markdown or text file:

aspell check README.md

If aspell flags a variable name, function name, course abbreviation, or technical term, do not change it blindly. Use judgment.

doxygen#

doxygen can generate documentation from structured comments in source files. It is most useful when your program has functions, classes, or multiple files.

Create a starter configuration file:

doxygen -g Doxyfile

Then edit Doxyfile as needed. Common settings include:

PROJECT_NAME = "CS Project"
INPUT = .
RECURSIVE = NO
EXTRACT_ALL = YES

Generate documentation:

doxygen Doxyfile

The generated files usually go into an html directory. Open html/index.html in a browser to inspect the documentation.

Doxygen output is not a substitute for the required comments in your source file. Follow the course-required header comments and function comments first.