Skip to main content

Appendix A - Style Guide

When you write programs professionally, you need to be able to have consistent styling. Consistent styling makes your code easier to read and update. These mostly come down to habits... it is better to develop this habit early. If you write your code with a style in mind, it will make your programs easier to read and understand. It will make your own program easier to write because it will make your logical decisions easier to understand. This guide will go over some of the most important aspects of styling your code

There are different opinions when it comes to exact styling. When you go and work, your company could very well have a code styling guide that they expect you to follow. This is to make the code that you write fit together with your co-workers' code. Your code may be rejected if you do not follow code styling guidelines even if it works! Knowing the rules matter. Below are the rules we expect you to follow when writing your programs for this course. You will be expected to follow these styling rules when you write your programs and your grade will be affected if these conventions are not followed.

Naming Conventions​

For any thing where you must provide a name use the following guideline

The Names​

  • all names must be descriptive. The name is part of the documentation so use a descriptive name.
  • single character variable names are not allowed unless they are part of a commonly known naming convention
    • i, j and k are allowed as loop counters in for loop. They must be used in that order. If it is a single for loop, the counter is i. If you have a for loop inside another for loop, the outer most loop is i, the inner loop is j.
		for(i = ...){
			for(j = ... ){
				for(k = ...){
					...
				}
			}
		}
  • x, y and z are only allowed if they are used to store coordinates

casing​

function, parameters and variable names​

Declare functions, variables and parameters in lower camelcase. To create a name that is lower camel case, write all words of the descriptive name in all lower case. Starting with the second word, capitalize the first character of the word.

Examples:

widthOfCar startingSalary hoursWorked

structs​

Declare the name of a struct (not the instance.. the struct itself) in upper camel case. This casing capitalizes the first character of every word including the first.

Examples:

EmployeeRecord MedalStandings VideoPlaylist

consistent conventions​

There are other naming conventions that some programmers adopt. For example, some programmers use something called "Hungarian Notation"...(came from Charles Simonyi, a Hungarian-American developer in the early days of Microsoft). Hungarian Notation adds extra characters to describe the types of the variables. For example, instead of using just ageOfPet, you would indicate that it is an integer by using iAgeOfPet.

These kind of naming conventions can be divisive and controversial. Some were created to address language related issues. It doesn't mean its good in the languages we use today! While we will leave it to you to decide if you want to adopt something such as "Hungarian Notation", you must consistently follow the convention. Do not sometimes use it but sometimes not use it. It is either all or nothing.

Code blocking​

In C, the curly brackets, , are used to create blocks of code. Here are the rules of where to place these curly brackets

For functions and struct declarations put the opening curly bracket on the next line.

struct MyStruct
{
	//struct member declaration goes here
};

void myFunction(...)
{
	//code goes here
}

For control structures such if/else/for/while/do-whiles, put the opening curly on the same line as the control structure

if(...){

}
for(...){

}

While C does allow you to not use curly brackets if there is only one statement in the control structure, it is bad habits. You are expected to always use curly brackets with your control structures

Indentation​

  • Use 4 spaces for indentation size.
  • You may choose to use tabs or spaces for indentation BUT, you must use one or the other. You cannot mix it.
  • Every code block that is inside another code block needs to be indented one indentation

Comments​

Comments make your code easier to read but there is a balance that must be maintained. Too little comments and reading your program becomes a huge slog. Comment too much and you risk creating "sacred text" in your program. These are comments that are for one reason or another never modified even when the code changes. At some point the code and comments mismatch and the reader is left to decide whether the code is wrong or the comment is wrong. This is not a good thing.

Required documentation​

  • Every function that you write requires documentation. This documentation must include the following:
    • high level description of what your function will do. (be clear about the "what", not the "how")
    • parameters to the function - what the function is expecting and any limitations
    • what the function returns - what is the function suppose to return
  • Anytime where you are doing something that is not clearly obvious
  • Extended descriptions that would have made names too long

Comment do's and don't's​

Do's​

  • DO state intentions
  • DO state things that go beyond names (like units)
  • DO state for each function what it accepts, what it returns and what it does (at a high level), special cases, etc.

Don'ts​

  • DON'T state the obvious
  • DON'T write line by line comments that mirrors the code... documentation is about intention. You want to state why are you doing something instead of what you are doing. The what should be obvious from the code. The intention is not always obvious and needs documentation.