01.04.2017, 17:43
Maintenance best practices
Naming conventions
What and why
A naming convention is a set of rules that dictates how variables and functions should be named, and which all members working on a project should follow. This ensures that other team members can read the code someone else has written. Even if you're working on a project by yourself you should still stick to your rules. If you come back to your old code in a few months time it will still be understandable.
Now, these guidelines are largely dictated by the programming language that is used (for example in .NET you would start a function name with a capital letter while in Java you wouldn't) but there's nothing stopping you from creating your own rules. It is only important that you stick to your rules.
Example rules
Here I will list some example rules that I use.
General
All code is in the English language. Comments need not be.
Definitions and other Constants
Are written in ALL_UPPER_CASE_WITH_UNDERSCORES.
Enumerators and enum specifiers
Are also constants and as such follow the same rules. Additionally they are prefixed with E_.
Functions
Use PascalCase.
Always contain a verb. (Get, Set, Show, Hide, Create, Destroy, etc.).
Functions that return a boolean value (true or false) will start with the word "Is" (e.g. IsPlayerInArea()).
Variables
Are written in camelCase.
Must convey purpose, not type.
Must not be abbreviations.
Single letter variables are reserved for loop iterators (i).
Boolean variables start with "is" or "has".
Are always singular.
Good: message, name, itemList, hasFinished. Bad: string, str, param, tmp.
Global variables
Are additionally prefixed with the letter g.
Arrays
Are always plural, but otherwise they follow the same rules as other variables.
About Hungarian Notation
Most of you will have seen this or even used it in some form. Perhaps without recognizing it, perhaps "because everyone else does it". There are two form of Hungarian Notation: Systems Hungarian, which prefixes variable names with their type, and Apps Hungarian which prefixes variables with their purpose.
I adamantly do not advocate the use of Systems Hungarian. Knowing a variable's purpose implies knowing its type. How often I have seen "szString". This is double redundant: sz means "string, zero-terminated". And then you name the variable ... string. And then you still don't know what is actually stored in that variable. Better would be "szMessage" but even then it would be painfully obvious that a message contains text (i.e. a string). Systems Hungarian has very little use and I only use it for enum specifiers (E_) to distinguish them from other constants.
Apps Hungarian has its uses, but if it is overused it will make the code harder to read (subjective). I will use this for globals (g) but not really anything else. I suppose you could prefix variables that store textdraw with "td" or "textDraw" and variables that store timers with "tmr" or "timer", but that's totally up to you.
Naming conventions
What and why
A naming convention is a set of rules that dictates how variables and functions should be named, and which all members working on a project should follow. This ensures that other team members can read the code someone else has written. Even if you're working on a project by yourself you should still stick to your rules. If you come back to your old code in a few months time it will still be understandable.
Now, these guidelines are largely dictated by the programming language that is used (for example in .NET you would start a function name with a capital letter while in Java you wouldn't) but there's nothing stopping you from creating your own rules. It is only important that you stick to your rules.
Example rules
Here I will list some example rules that I use.
General
All code is in the English language. Comments need not be.
Definitions and other Constants
Are written in ALL_UPPER_CASE_WITH_UNDERSCORES.
Enumerators and enum specifiers
Are also constants and as such follow the same rules. Additionally they are prefixed with E_.
Functions
Use PascalCase.
Always contain a verb. (Get, Set, Show, Hide, Create, Destroy, etc.).
Functions that return a boolean value (true or false) will start with the word "Is" (e.g. IsPlayerInArea()).
Variables
Are written in camelCase.
Must convey purpose, not type.
Must not be abbreviations.
Single letter variables are reserved for loop iterators (i).
Boolean variables start with "is" or "has".
Are always singular.
Good: message, name, itemList, hasFinished. Bad: string, str, param, tmp.
Global variables
Are additionally prefixed with the letter g.
Arrays
Are always plural, but otherwise they follow the same rules as other variables.
About Hungarian Notation
Most of you will have seen this or even used it in some form. Perhaps without recognizing it, perhaps "because everyone else does it". There are two form of Hungarian Notation: Systems Hungarian, which prefixes variable names with their type, and Apps Hungarian which prefixes variables with their purpose.
I adamantly do not advocate the use of Systems Hungarian. Knowing a variable's purpose implies knowing its type. How often I have seen "szString". This is double redundant: sz means "string, zero-terminated". And then you name the variable ... string. And then you still don't know what is actually stored in that variable. Better would be "szMessage" but even then it would be painfully obvious that a message contains text (i.e. a string). Systems Hungarian has very little use and I only use it for enum specifiers (E_) to distinguish them from other constants.
Apps Hungarian has its uses, but if it is overused it will make the code harder to read (subjective). I will use this for globals (g) but not really anything else. I suppose you could prefix variables that store textdraw with "td" or "textDraw" and variables that store timers with "tmr" or "timer", but that's totally up to you.
