Coding Guidelines

Every programming language has its own set of stylistic conventions that are meant to promote readability. It is a very important aspect of software development that is heavily stressed by many companies, including: Google, Amazon, Microsoft, Mozilla, Apache, Chromium, TensorFlow, React Native, HyperLedger, Visual Studio Code to just list a few. Your future employers value good style and hence, the CSE department is committed to help you develop the skills required for a successful career

While everyone agrees that improving readability of a program is desirable, there are different ideas on how to achieve that. For example, Acme Software Inc. may insist that their C++ programmers prefix all data members with "m_" (e.g., m_examScore, m_name), while another company may not have this requirement. An Internet search on programming conventions will yield dozens of stylistic conventions, for dozens of different languages. Some of these documents will approach being one hundred pages long!

This document is not meant to be yet another all-encompassing document on coding conventions. Instead, it provides references to widely used style guidelines for different programming languages. In addition, it summarizes a small set of key ideas from them with the objective of guiding beginning and intermediate level programmers in some of the fundamental aspects of programming style. Although, there is not a concrete set of rules, you can generally rely on the following rules:

• Keep it simple
• Strive for clarity
• Be consistent
• Follow other well-established standards, if possible

For those interested in the motivation and rationale behind many of these style guidelines, please refer to "The Art of Readable Code", by Dustin Boswell and Trevor Foucher (ISBN: 978-0596802295). All Miami students, faculty, and staff have free access to the electronic version of this textbook via the: Safari on-campus link for "The Art of Readable Code" or Safari off-campus link for "The Art of Readable Code"

Style guides for common programming languages

Here are a few existing coding conventions for some of the common programming languages that the CSE department uses:

• C++ Style Guidelines
  • CSE department's C++ style checker for Linux & Mac
• Java Style Guidelines
  • Java style checker and associated style rules (one zip file)
• Python Style Guidelines
• C# Style Guidelines
• Visual Basic Style Guidelines

Key style requirements

Most IDEs will typically allow you to configure your style preferences and automatically format your code to fit these guidelines. Ensure you check your IDE's settings to ensure it is consistent with CSE department’s guidelines.

Your instructor might have additional or modified versions of these requirements. When in doubt, check with your instructor.

Indentation, Whitespace, Line Wrapping, and Method Size

Indentation and whitespace should be used to improve the readability of your programs. This is a principle that holds in all programming languages. Indentation should be used to emphasize the nesting of control structures, while adhering to the following expectations:

• Indent using only spaces (not tabs).
• There must be a blank space between keywords as in:
  
  • Wrong (missing spaces):
    
    • int area=Math.PI*Math.pow(r,2);
    • for(int i=0;i<10;i++)
  • Correct (with spaces):
    
    • int area = Math.PI * Math.pow(r, 2);
    • for (int i = 0; (i < 10); i++)
• Blank lines should be judiciously used to separate code sections that are performing logically different tasks
• Lines longer than 80 characters should be wrapped onto the next line in a manner that enhances readability

Note: Most IDEs will alow you to configure your style preferences and the IDE will automatically format your code, making it very convenient. Ensure you check out your IDE options before manually reformatting your source code.

• It is highly recommended to have short methods, typically 25-lines of code (25-lines does not include comments or blank lines)

Bracing

The bodies of conditionals and loops must be surrounded by braces, {}. The following examples recommended bracing style based on programming language(s):

Note: even if the body of the if-else constructs has only a single statement, the braces must be used. Additionally, do not adopt a style that deemphasizes, or hides, the bracing:

Comments (see examples in source code further below)

Regardless of the language, every file should have the following information. When possible, you should use any conventions that allow the automatic generation of documentation (e.g., C++, Java and C#):

• Your name
• Instructor's name
• Course number and section
• Description of the file's contents
• Statement identifying code segments that were developed in full, or in part, by another person

Each function or method will typically have the following information (see examples in source code further below):

• Name of Method
• Description of what method does. Include time complexity information, if known.
• Assumptions that the method makes
• Description of each parameter and its acceptable range of values
• Description of return value
• Example usage, if it would help clarify how to use it

Naming conventions for classes, variables, etc.

There are three common conventions for naming programmatic entities. These are Pascal case, camel case, and uppercase. Pascal case capitalizes the initial letter of each word. Camel case is similar, but does not capitalize the first word. Uppercase uses all uppercase characters, but separates the words with an underscore. Here are some examples:

• Pascal Casing or Title casing - TestCounter
• Camel Casing - testCounter
• Uppercase - TEST_COUNTER

• Class/struct: TitleCase
• Types: TitleCase
• Interface: TitleCase (for C#, prefix with "I")
• Enum type: TitleCase
• Enum value: TitleCase
• Fields/data members: camelCase
• Methods/property: camelCase (for Java & C++) vs. TitleCase for C#
• Namespace/package: lowercase (for Java & C++) vs. TitleCase for C#
• Constants: UPPERCASE