SA-MP Forums Archive
[Tutorial] Maintenance best practices: naming conventions - Printable Version

+- SA-MP Forums Archive (https://sampforum.blast.hk)
+-- Forum: SA-MP Scripting and Plugins (https://sampforum.blast.hk/forumdisplay.php?fid=8)
+--- Forum: Scripting Help (https://sampforum.blast.hk/forumdisplay.php?fid=12)
+---- Forum: Tutorials (https://sampforum.blast.hk/forumdisplay.php?fid=70)
+---- Thread: [Tutorial] Maintenance best practices: naming conventions (/showthread.php?tid=631607)


Maintenance best practices: naming conventions - Vince - 01.04.2017

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.

Re: Maintenance best practices: naming conventions - princejeet1510 - 01.04.2017

Woah another good suggestion and I'd say "guideline" not a tutorial though :P but you always got something which is useful for REAL PROGRAMMERS.

Re: Maintenance best practices: naming conventions - Logic_ - 01.04.2017

Give this guy some Doritos... oh well, I mean Kudos

On-Topic:
Amazing advises that are actually 'guidelines'

Re: Maintenance best practices: naming conventions - SyS - 02.04.2017

There are some standard naming conventions too which are universal to all type of programming/scripting languages.
They are :and also i would recommend to use prefixes for file handlings too. Like TypeOffile_File.

Re: Maintenance best practices: naming conventions - Hansrutger - 02.04.2017

Don't tell me what to do! :C

No for real really good guidelines, hope this helps people understand the importance in readable code. And if it doesn't, please don't consider an employment that includes you coding. :3 But highlighting this sentence especially: "It is only important that you stick to your rules."

Good job!

Re: Maintenance best practices: naming conventions - JustMe.77 - 12.05.2017

This is a great tutorial, well explained

Re: Maintenance best practices: naming conventions - Yousha - 14.05.2017

Thanks, but:

Quote:

"up to you" "its common" "you would" "maybe you like" etc...
It's more like naming suggestion than naming Convention
In conventions you must use "Must" and "Must Not"

Also could be better with Project structure, file names, resources, code indent, Line length, parameters...