26.04.2011, 15:59
(
Последний раз редактировалось Sinner; 26.04.2011 в 17:44.
)
Introduction
I'd like to point out, that anything said below doesn't apply to experienced coders, since they all have developed their own programming style and perfectly know how to bring structure to code. Also, anything said is my own opinion and I'm not stating that my ways are "the" way to do it. I can image people like ****** and Kalcor use totally different ways to program, but after all, I'd love some objective criticism.
-
At first some may think, why should I make my code readable? It works, what's the big deal? And fact is, if you're writing a very straight-forward piece of code this applies, there's little to read and so it doesn't really matter if it's "wel-formed" or not. But once you start scripting bigger gamemodes, making your code readable is EXTREMELY important, because if you need to change something (could be something very trivial) and your gamemode is a mashup of chaotic coding styles that are not in any way properly written, you could end up throwing your PC out the nearest open window because of the frustration.
Part 1: Proper indenting
Indenting is THE most important part of making your code readable, but some people don't do it properly and avoid warning by simply doing:
Throughout your entire script, try maintaining the same tabsize for all indents. Commonly used are 4 spaces or a TAB (which has the same width as 4 spaces). Although it's fine to use 2 or 3 spaces, it makes code less readable (depending on your editor) because everything will seem more packed together. Never use more then 4 spaces.
Indenting should be done in the following cases:
a) Whenever you use curly brackets, indent the next snippet by 1, like so:
You immediatly see that this is way more readable then for example this:
In this snippet, it's very hard to see where the function ends and starts, since the curly brackets add up.
b) Whenever your statement is too long:
When statements get too long, it's wise to indent them to make it more readable, don't worry, as long as it's 1 statement the compiler wont care about the carriage return.
Example with a very long format function:
Part 2: Proper use of curly brackets
Just as important as indenting, is properly using curly brackets. Here is where there are 2 commonly accepted methods, some place the brackets parallel to each other, while other like to keep the first bracket next to the corresponding statement, seperated by a space. Both methods are fine and commonly used, but I prefer the first one since it's more readable (prove me wrong O.o).
Example method 1:
Example method 2:
Decide to yourself which you like best. The trick to never forget a bracket ever again, is to always immediatly place the 2 brackets before even starting to code the next group of statements. This way, if there are many nested statements, you won't have to search for which bracket you didn't properly close. Also, if you forget a curly bracket it'll immediatly give lots of errors, making it even harder to find your mistake.
Part 3: Use #define(s)
Defines are easy to use and can not only make your code more readable, but it makes it possible to change a lot of data by changing 1 line. If not properly defined though, defines can give nasty errors that are very hard to find if you're unaware of your mistake, since the error line will point to the place where you used the define, not where the define is created.
a) What are defines?
Defines are no more then "copys" of a certain statement, whenever you use a define you are just using whatever statement you defined it as.
b) How to properly use defines
I always like to put round brackets around my defines, this way you prevent it from messing up your statement. Well known example are defines that make a calculation, which will return a wrong result if you don't put your round brackets in the right places. I won't be going any further into how to properly use defines as this is not a tutorial about that.
Defines are created like this:
Part 4: Use #include(s)
Includes help to reduce the lines of code in a script, by simply gathering functions/defines instead of writing these functions/defines in the gamemode. A big advantage is that you can use includes in other Filterscripts aswell as oppose to writing the same functions/defines all over again in every script you need them in, it's a lot better to just store these functions somewhere, in a place where all scripts can access them (.INC file). Typically includes are used to define colors, dialog ids, general purpose variables and functions, etc...
You include a file by writing:
"filename" referring to the .INC file in your PAWNO/INCLUDES/ folder
An example of the content of an include file could be the following:
Now every FS/Gm that has this file included can use these colors, abbreviations, vworlds and dialog ids.
Part 5: Use functions
If you don't know how to write functions, learn it! They are the backbone of every good script. Functions are if not the most important thing you'll ever learn as a programmer. In fact, you'll never be a good programmer if you don't know how to write and declare a function. Functions make your code readable and (if written properly) are easy to use.
Since functions make your code so much readable, it's perfectly fine to use a function in a function, in a function, in ... Infact, it's ok to use as many nested functions as you want (as long as they make sense).
Part 6: Write comments/document your code!
I cannot stress this enough, you should place comments everywhere! It may be that you perfectly know what a function/statement does but believe me, X months later you won't remember it (if the function/statement is complicated enough). This is why it's so important to properly document your code. Whenever you're not sure if you'll remember what something will do don't be afraid to write a whole page of information about the snippet next to it, since it can only help you. Comments don't harm anyone and they don't increase the filesize of your .AMX file since the compiler ignores them, so why not use them?
I'd say, good code has just as many lines of comments then it has statements (if not more).
Part 7: Use whitespaces
This is not mandatory, but it's recommended you leave a line open between each function and/or callback. This makes your code more readable.
I hope you enjoyed and/or learned something from this tutorial, any feedback is appreciated
EDIT: Thanks @Hiddos for pointing out a mistake
I'd like to point out, that anything said below doesn't apply to experienced coders, since they all have developed their own programming style and perfectly know how to bring structure to code. Also, anything said is my own opinion and I'm not stating that my ways are "the" way to do it. I can image people like ****** and Kalcor use totally different ways to program, but after all, I'd love some objective criticism.
-
At first some may think, why should I make my code readable? It works, what's the big deal? And fact is, if you're writing a very straight-forward piece of code this applies, there's little to read and so it doesn't really matter if it's "wel-formed" or not. But once you start scripting bigger gamemodes, making your code readable is EXTREMELY important, because if you need to change something (could be something very trivial) and your gamemode is a mashup of chaotic coding styles that are not in any way properly written, you could end up throwing your PC out the nearest open window because of the frustration.
Part 1: Proper indenting
Indenting is THE most important part of making your code readable, but some people don't do it properly and avoid warning by simply doing:
Код:
#pragma tabsize 0
Indenting should be done in the following cases:
a) Whenever you use curly brackets, indent the next snippet by 1, like so:
PHP код:
function Example(void)
{
// Indent
if(something ==TRUE)
{
//Indent
DoSomething();
}
}
PHP код:
function Example(void){
if(something ==TRUE)
{
DoSomething();
}
}
b) Whenever your statement is too long:
When statements get too long, it's wise to indent them to make it more readable, don't worry, as long as it's 1 statement the compiler wont care about the carriage return.
Example with a very long format function:
PHP код:
format(carmenu, sizeof(carmenu), "Nos %s\nBoost %s\nColor1 %s\nColor2 %s\nJump %s\nWheels %s\nHydraulics %s\nAutofix %s\nRamps %s\nBike Antifall %s\nFast Entering: %s\nFast Exiting: %s",
__state[0],__state[1],__state[2],__state[3],__state[4],__state[5],
__state[6],__state[7], __state[8], __state[9], __state[10], __state[11]);
Just as important as indenting, is properly using curly brackets. Here is where there are 2 commonly accepted methods, some place the brackets parallel to each other, while other like to keep the first bracket next to the corresponding statement, seperated by a space. Both methods are fine and commonly used, but I prefer the first one since it's more readable (prove me wrong O.o).
Example method 1:
PHP код:
function Example(void)
{
if(isSomethingTrue())
{
// Do something here
}
}
PHP код:
function Example(void) {
if(isSomethingTrue()) {
// Do something here
}
}
Part 3: Use #define(s)
Defines are easy to use and can not only make your code more readable, but it makes it possible to change a lot of data by changing 1 line. If not properly defined though, defines can give nasty errors that are very hard to find if you're unaware of your mistake, since the error line will point to the place where you used the define, not where the define is created.
a) What are defines?
Defines are no more then "copys" of a certain statement, whenever you use a define you are just using whatever statement you defined it as.
b) How to properly use defines
I always like to put round brackets around my defines, this way you prevent it from messing up your statement. Well known example are defines that make a calculation, which will return a wrong result if you don't put your round brackets in the right places. I won't be going any further into how to properly use defines as this is not a tutorial about that.
Defines are created like this:
PHP код:
#define [name of define] [statement]
// for example
#define MULTIPLY(%0, %1) ((%0) * (%1))
Includes help to reduce the lines of code in a script, by simply gathering functions/defines instead of writing these functions/defines in the gamemode. A big advantage is that you can use includes in other Filterscripts aswell as oppose to writing the same functions/defines all over again in every script you need them in, it's a lot better to just store these functions somewhere, in a place where all scripts can access them (.INC file). Typically includes are used to define colors, dialog ids, general purpose variables and functions, etc...
You include a file by writing:
PHP код:
#include <"filename">
An example of the content of an include file could be the following:
PHP код:
#define COLOR_YELLOW 0xFFDD00AA
#define COLOR_GREY 0xAFAFAFAA
#define COLOR_REDONLY 0xE60000FF
#define SCRIPT_HELP "/help"
#define SCRIPT_COMMANDS "/commands"
#define SCRIPT_TELEPORTS "/teles"
#define LMS_DMZ_VWORLD (27)
#define GANGDM_DMZ_VWORLD (28)
#define DW_DMZ_VWORLD (29)
#define VWORLD_VIP (30)
#define DIALOG_AUTOFIX (100)
#define DIALOG_CARMENU (101)
#define DIALOG_CARMENU_COLOR1 (102)
Part 5: Use functions
If you don't know how to write functions, learn it! They are the backbone of every good script. Functions are if not the most important thing you'll ever learn as a programmer. In fact, you'll never be a good programmer if you don't know how to write and declare a function. Functions make your code readable and (if written properly) are easy to use.
Since functions make your code so much readable, it's perfectly fine to use a function in a function, in a function, in ... Infact, it's ok to use as many nested functions as you want (as long as they make sense).
Part 6: Write comments/document your code!
I cannot stress this enough, you should place comments everywhere! It may be that you perfectly know what a function/statement does but believe me, X months later you won't remember it (if the function/statement is complicated enough). This is why it's so important to properly document your code. Whenever you're not sure if you'll remember what something will do don't be afraid to write a whole page of information about the snippet next to it, since it can only help you. Comments don't harm anyone and they don't increase the filesize of your .AMX file since the compiler ignores them, so why not use them?
I'd say, good code has just as many lines of comments then it has statements (if not more).
Part 7: Use whitespaces
This is not mandatory, but it's recommended you leave a line open between each function and/or callback. This makes your code more readable.
I hope you enjoyed and/or learned something from this tutorial, any feedback is appreciated
EDIT: Thanks @Hiddos for pointing out a mistake
I was going to add something like this in my big scripting beginners guide, but Instead I shall link to this 
