Programming styles

Introduction

A programming style is a set of guidelines used to format programming instructions. It is useful to follow a style as it makes it easier for programmers to understand the code, maintain it, and assists in reducing the likelihood of introducing errors. Guidelines can be developed from coding conventions used in an organisation with variations of style occurring for different programming languages. Key elements of programming style guide include naming conventions, use of comments and formatting (indenting, white spaces). In some languages (e.g. Python), indenting is used to indicate control structures (hence correct indentation is required), whilst in other languages indenting is used to improve the visible appearance and readability of the code (e.g. Java).

Naming conventions

When naming variables, functions/methods, classes, files etc. it is important to follow a naming convention, and use correct English spelling (this assists with search/find/replace operations). Naming conventions are used to improve visual appearance and reduce the effort needed to read and understand the code. They can vary in different programing languages. The following items are a good guide:

  1. All naming should be descriptive where appropriate.
  2. Avoid abbreviation where possible but seek to keep naming an appropriate mix of easy to understand purpose but not too long.
  3. Spaces must not be used. Some languages would use dashes for names (e.g. total-height in Lisp), while other languages would use an underscore (e.g. total_height in Python, SQL). Java uses mixed case for variables starting with lowercase e.g. totalHeight.
  4. Constants are usually defined as all uppercase using underscores to separate words. e.g.MAX_HEIGHT.

Commenting

Comments improve program readability. As with naming conventions, it is important to use correct English spelling. Please note that different programming languages (dis)allow differernt commenting styles.

  1. Be consistent with your use of commenting syntax, for example:
    1. // This is a line comment
    2. /* This is a block comment
    3. over two lines */
    4. -- This is a comment
  2. Start each file with a comment at the top describing its contents.
  3. Start each class with an accompanying comment that describes what it is for and how it should be used.
  4. Start each function with a comment describing use of the function.
  5. Variable names should be descriptive enough not to require commenting. If this is difficult, provide a brief comment at declaration.
  6. Only comment tricky, non-obvious, interesting or important parts of your code throughout implementation.
  7. Follow normal grammatical conventions to ensure readability of comments.

Indenting and Whitespaces

  1. Indenting and Whitespace requirements for particular languages supersede any general guidelines (such as Python requirements)
  2. Blank lines should be used to separate logical groupings of code
  3. Minimum of 2 blank lines should be used to separate functions
  4. Be consistent with choice of tabs or spaces for indenting. Adjust tab sizing so as not to be too large.
  5. Aim for best readability. Primary importance is that code is easy to read and logically follow. For example:
    1. a = (b + c) * d;
    2. // is more readable than:
    3. a=(b+c)*d
    4. while (true) {}
    5. // is more readable than:
    6. while(true){}
    7. for  (i  =  0;  i  <  10;  i++) {}
    8. // is more readable than
    9. for(i=0;i<10;i++){}
    10. if  (conditionA && conditionB) {
    11.     doSomething;
    12. }
    13. else {
    14.     doNothing;
    15. }
    16. // is more readable than:
    17. if (conditionA&&conditionB)
    18. {doSomething;}
    19. else{doNothing;}

General formatting

  1. Keep line lengths to 80 characters or less where appropriate.
  2. Adopt the same formatting conventions as previously written code if adding to or modifying an existing code base.
  3. BE CONSISTENT!

Style for your language and your unit

Check on the specific convention and style to be used for your programming language, and write your code using the style guide. Many units within the Faculty will provide more detailed style guides or other instructions on code style, and these should always be followed where they exist. If you are unsure of the style to be used for a particular assignment, you should consult with the teaching staff for that unit.

Your opinion on this page: Feedback