SA-MP Forums Archive
[Tutorial] How to make clean and readable code - 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] How to make clean and readable code (/showthread.php?tid=251335)



How to make clean and readable code - Sinner - 26.04.2011

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:
Код:
#pragma tabsize 0
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:
PHP код:
function Example(void)
{
    
// Indent
    
if(something ==TRUE)
    {
        
//Indent
        
DoSomething();
    }

You immediatly see that this is way more readable then for example this:
PHP код:
function Example(void){
if(
something ==TRUE)
{
DoSomething();
}

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:
PHP код:
format(carmenusizeof(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]); 
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:
PHP код:
function Example(void)
{
    if(
isSomethingTrue())
    {
        
// Do something here
    
}

Example method 2:
PHP код:
function Example(void) {
    if(
isSomethingTrue()) {
        
// Do something here
    
}

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:
PHP код:
#define [name of define] [statement]
// for example
#define MULTIPLY(%0, %1)    ((%0) * (%1)) 
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:
PHP код:
#include <"filename"> 
"filename" referring to the .INC file in your PAWNO/INCLUDES/ folder

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


Re: How to make clean and readable code - Hiddos - 26.04.2011

I'm an asshole for pointing out, but you've got 'Part 4' twice.

Anyways, +1 for this tutorial as there amazingly enough are too much people who don't understand properly indenting their code.


Re: How to make clean and readable code - Sinner - 26.04.2011

Quote:
Originally Posted by Hiddos
Посмотреть сообщение
I'm an asshole for pointing out, but you've got 'Part 4' twice.

Anyways, +1 for this tutorial as there amazingly enough are too much people who don't understand properly indenting their code.
Haha, no you're totally right, I'll fix that straight away!


Re: How to make clean and readable code - Unknown1234 - 26.04.2011

most newb will learn from it
+5


Re: How to make clean and readable code - [MWR]Blood - 26.04.2011

Nice tutorial, good job!
Useful for beginners


Re: How to make clean and readable code - Sinner - 27.04.2011

Quote:
Originally Posted by [HLF]Southclaw
Посмотреть сообщение
Great tutorial I was going to add something like this in my big scripting beginners guide, but Instead I shall link to this Good work
Thanks, I feel honored


Re: How to make clean and readable code - xir - 28.04.2011

Nice tutorial but use [ pawn ] [ / pawn ] tags


Re: How to make clean and readable code - XFlawless - 28.04.2011

This tutorial is really use for beginners who can start clean coding.


Re: How to make clean and readable code - ScRaT - 28.04.2011

yea
nice tutorial
09/10


Re: How to make clean and readable code - TheGarfield - 28.04.2011

tree method:

pawn Код:
#include <a_samp> // Method 1
#include "a_samp>  // Method 2
#include a_samp     // Method 3
this is for all iqual!

Nice tutorials, congratulations!