Programming Style Documents

Here are the documents on programming style that I've written and am making available to you. Why am I doing this? Simple: I want you to follow these guidelines when you write programs in my classes! Read them through, print them out if you'd like, and follow them as you write your programs for class.

---

A Piece of Advice
Document while you're writing your program, not after you have it working correctly.
Everyone who will have to look at your unfinished but well-documented program will appreciate the explanations.

---

Documents in this section are applicable to any programming language:

• Programming Style Requirements -- A one-page summary (PDF format) of the documentation requirements of the course. I recommend that you keep a copy of this handy for reference as you write your programs. Failure to document your programs in accordance with these requirements will result in a loss of points when I grade your program.

If you are using Java, take a look at these:

• How to Develop a Simple Java Program -- Designed for students just learning Java, this document takes a simple programming assignment and shows, step by step, how to go about developing a Java program to solve the problem, how to document the program, and how to produce a printout suitable for handing in. NOTE: The commenting templates in this example are a bit different from what I now require.
• Block Comment Templates with Examples -- Doing internal and external block comments is much easier if you have a template to fill in with the details. Here is an HTML version of the templates, for Java, along with directions on how to include them in your program and an example or two.
• For indentation, even though C and Java are not the same, they are similar enough that I think my Indenting C Programs document is adequate to get the points across for Java, too.
• Oracle's Java Code Conventions -- Sun's Java style guide, based on a C style document from AT&T and Sun (and available below).

If you are coding in Python, take a look at these:

• How to Develop a Simple Python Program -- Designed for students just learning Python, this document takes a simple programming assignment and shows, step by step, how to go about developing a Python program to solve the problem, and how to document the program.
• Unlike Java and C, Python programs are required to be indented consistently (or else the program can't be run!). That's why, unlike the Java and C sections below, I don't have a page of suggestions for documenting Python. Stick with 4 spaces per level of indentation, and you'll be fine.
• Style Guide for Python Code -- Guido van Rossum's Python programming style guide. Guido is the father of Python; the man knows of what he writes. Yes, it's long. Consider that to be an indication of the importance of good programming style.

If you are using C or even C++, take a look at these:

• How to Develop a Simple C Program -- Designed for students just learning C/C++, this document takes a simple programming assignment and shows, step by step, how to go about developing a C program to solve the problem, how to document the program, and how to produce a printout suitable for handing in.
• Toward Developing Good Programming Style -- The C language version of a document that shows how to apply the rules given in the Programming Style Requirements document to a sample C program.
• Block Comment Templates with Examples -- Doing internal and external block comments (as demonstrated in the style examples, above) is much easier if you have a template to fill-in with the details. Here is an HTML version of the templates, along with directions on how to include them in your program and an example or two. NOTE: This includes both C and Pascal templates.
• Indenting C Programs -- Some students just don't seem to catch on to the idea of indenting program statements to improve code clarity, so I created this page. It shows how to acceptably indent a variety of common C control structures.
• Recommended C Style and Coding Standards -- This is an HTML version of an updated version of the classic Indian Hills C Style and Coding Standards paper. It covers a wide range of topics.
• Recommended C Style and Coding Standards (Postscript version) -- Same as the above, but in Postscript format.
• C Style and Coding Standards (Postscript) -- a style document created by programmers at AT&T Information Systems and Sun Microsystems.
• Sun Microsystem's Java Code Conventions -- The previous document, being available only in Postscript, may be hard for you to access. But, here is their Java style guide, and it is based on that C document. Java does have many similarities to C, so reading through these documents can still be beneficial to C programmers.

For those of you more interested in developing Pascal programs, here are some documents written for you:

• Toward Developing Good Programming Style -- The Pascal language version of a document that shows how to apply the rules given in the Programming Style Requirements document to a sample Pascal program.
• Block Comment Templates with Examples -- Doing internal and external block comments (as demonstrated in the style examples, above) is much easier if you have a template to fill-in with the details. Here is an HTML version of the templates, along with directions on how to include them in your program and an example or two. NOTE: This includes both Pascal and C templates.

If you have any comments about this page, drop me a note at mccannl@acm.org

Return to Ol' Doc McCann's Home Page