3.2. Code style guide

In general, there are many ways in which you can format or layout your code, all of which will work. That said, how you layout your code can have a big impact on how easy it is to read and to debug.

Most companies will have an internal style guide for how to structure and format code so that it looks consistent between different developers and is easy for different people to work on the same codebase. In large projects there may be many different people coding different parts of the program. For example, you can view the Google style guide. Python as a language has an official style guide known as PEP 8. Rust also has an official style guide.

There are also automatic tools that you can use to check your code style against a standard, and to automatically convert code between different styles. In our setup of VSCode we automatically turn these on to help with formatting your code. You’ll find that your code gets re-formatted by the auto-formatter each time you save it. Beyond this, we don’t have a strictly enforced style guide. For assessed parts of the course, you’ll receive marks whatever style you use.

For writing these notes, we will use our own style, broadly following conventions common in Python and in Rust. In particular:

  • Filenames will be in snake case. That is, all lower case with underscores _ rather than spaces. Example: file_name.py. This is to help avoid cases like "file name.py" being accidentally interpreted as two files, one called "file" and one called "name.c". (Nevertheless, our code should use delimiters to mark the start and end of a filename to avoid this issue, because in general you can’t guarantee what a filename will be.)

  • Folders will be in kebab case. That is, all lower case with hyphens - rather than spaces. Example: lab-a. This is to help avoid issues with spaces in folder names, which can cause problems in some command line tools. (This is actually a fairly recent change to our style guide. You might still see some screenshots which use our older style, which used snake case for folders.)

  • Variables will be in snake case. Example: my_variable_name. Usually, but not always, programming is case sensitive, and so sticking with this helps ensure we don’t have My_variable and my_variable, which are actually two different variables.

  • Classes will be in Pascal case. That is, all lower case, with uppercase at the start of a new word, with no spaces present. Example: MyClassName.

  • Constants will be in capitals. Example: MY_CONSTANT.

  • We won’t use camel case. (Example: myVariableName.)

  • Code will be indented each time we move into a function, or into an if or while statement, or similar.

  • An indent is 4 spaces, entered with the space bar. We won’t use tabs for indenting. (This is because different computers may display tabs as having different widths, whereas a space is more fixed.)

  • Comments on the same line as code start with a lower case letter, as if they were continuing on a sentence. Comments on a line by-themselves start with an upper case letter, as if they are starting a new sentence.