SA-MP Forums

Go Back   SA-MP Forums > SA-MP Scripting and Plugins > Scripting Help > Tutorials

Reply
 
Thread Tools Display Modes
Old 01/04/2017, 05:43 PM   #1
Vince
Spam Machine
 
Vince's Avatar
 
Join Date: Sep 2007
Location: Belgium
Posts: 10,992
Reputation: 2649
Default Maintenance best practices: naming conventions

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.
__________________
Vince is offline   Reply With Quote
Old 01/04/2017, 05:46 PM   #2
princejeet1510
Big Clucker
 
princejeet1510's Avatar
 
Join Date: Mar 2016
Location: Trying to figure it out.
Posts: 117
Reputation: 4
Default Re: Maintenance best practices: naming conventions

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.
__________________
princejeet1510 is offline   Reply With Quote
Old 01/04/2017, 06:17 PM   #3
Logic_
High-roller
 
Logic_'s Avatar
 
Join Date: Jun 2015
Location: 666
Posts: 1,490
Reputation: 263
Default Re: Maintenance best practices: naming conventions

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

On-Topic:
Amazing advises that are actually 'guidelines'
__________________
Premium quality and reasonable pricing game Server hosting
Logic_ is offline   Reply With Quote
Old 02/04/2017, 01:17 AM   #4
SyS
High-roller
 
SyS's Avatar
 
Join Date: Oct 2015
Posts: 1,984
Reputation: 461
Default Re: Maintenance best practices: naming conventions

There are some standard naming conventions too which are universal to all type of programming/scripting languages.
They are :
  • c characters
  • i, j, k indices
  • n counters
  • s strings
and also i would recommend to use prefixes for file handlings too. Like TypeOffile_File.
SyS is offline   Reply With Quote
Old 02/04/2017, 04:24 PM   #5
Hansrutger
Gangsta
 
Hansrutger's Avatar
 
Join Date: May 2011
Location: Sweden
Posts: 928
Reputation: 158
Default Re: Maintenance best practices: naming conventions

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!
__________________


Hansrutger is offline   Reply With Quote
Old 12/05/2017, 07:07 PM   #6
JustMe.77
Huge Clucker
 
JustMe.77's Avatar
 
Join Date: Jun 2013
Location: Germany
Posts: 269
Reputation: 63
Default Re: Maintenance best practices: naming conventions

This is a great tutorial, well explained
JustMe.77 is offline   Reply With Quote
Old 14/05/2017, 07:21 AM   #7
Yousha
Banned
 
Join Date: May 2013
Posts: 123
Reputation: 7
Default Re: Maintenance best practices: naming conventions

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...

Last edited by Yousha; 14/05/2017 at 09:56 AM.
Yousha is offline   Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
[Tutorial] Maintenance best practices: coordinates Vince Tutorials 6 21/01/2017 11:19 PM
Database Naming bgedition Everything and Nothing 8 11/07/2016 08:52 PM
How do you all go around naming your versions? sammp Discussion 23 09/05/2015 07:09 PM
Help with Naming Zones AroseKhanNiazi Scripting Help 11 16/03/2014 07:06 AM
[Help] Naming the bots (NPC) TiNcH010 Help Archive 5 06/07/2011 04:18 PM


All times are GMT. The time now is 07:23 PM.


Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2018, Jelsoft Enterprises Ltd.