[HOWTO] Organize your code

Sometimes you need to share your knowledge. This is where you can do it. A place for POL and Script guides.
Post Reply
blckfire
Apprentice Poster
Posts: 54
Joined: Thu Feb 26, 2015 10:28 am

[HOWTO] Organize your code

Post by blckfire » Fri Dec 30, 2016 2:09 pm

Hi there! I'm blckfire and I've been developing code under a POL96 shard version. I also work as software developer/engineer.

Motivation
Looking at code from several people I understood that there is no standard set on how to write better code using POL. Because of that and because I think it's important that we follow some certain sets of guidelines to be able to write better and more readable code I decided to write a collection of small guides to help new/old POL scripters to write better code.
I by no means intend to set a standard on how to write code in POL and this guide should be used as guideline and then adjusted to your own projects if you wish to.

Table of contents
I'm going to discuss a little bit the importance of arranging and separating your code.

Separating your code
Q: What do you mean by, separating your code?
A: This has to do with how you should organize your code into files so that you can easily re-use your code and also make it easier for another person (mostly the you 6 months into the future) to read it and change it if/when necessary.

If you're developing a small package you can just stuff all your code into one file and use "Regions" to separate contents inside it but when you got a 2000 line .src or .inc file maybe it's better to try and separate all that content into smaller .inc files, making it easier for you to find the code you're looking for but also easier for another scripter to change code written by you. To accomplish this I normally tend to group functions into categories which then I use to make new .inc files.

For example, you made this new awesome package which has 10 different GUIs that are used at different points in time by the player. GUIs take a lot of place in your code and maybe you also want to make them accessible through a GM command so that a gm can check if some bug exists in the gump, because of this, is maybe better you stick all that as to do with gumps into one .inc file or even one per gump (depending on how complex your gump is and what sorts of functionality it implements). It is possible that within your package you have several functions that deal with some aspect of the package and these should be together, thus, making them the perfect candidate for a new .inc file.

Include files are one of the most amazing gifts of POL allowing you to access content of any package from any other package/script in your server giving you the opportunity to re-use your code in several spots of your game server. No more copy pasting code that is exactly the same and only adds redundancy to your code and confusion to other scripters.

Thus, we come to my conclusion that, ".src" files should be used to define your "script's logic" while your ".inc" files should contain your functionality.

Arranging your code
Arranging code has to do on how you should organize your functions inside your file and what comments you should add to your code so that it becomes more understandable for the next scripter that picks up your code (or the you 6 months into the future).

What I try to do in my code is to keep what has to deal with the same content all together. For example, in your package/script you have to do several operations thata theme related it is best to keep them all together.

Code: Select all

//Region Money Related

function AddMoney(character, quantity)
...
endfunction

function RemoveMoney(character, quantity)
...
endfunction

function CalculateMoneyOwed(character)
...
endfunction

function CalculateInterestOwed(character)
...
endfunction

//EndRegion
If you're using Notepad++ plus my UDL file you can create code regions this also helps to keep your code organized.

Another tool that makes your code more readable are the following code snippets:

Code: Select all

Scripts
/*
 *	File: scriptname.src
 *
 * Version:
 *
 *	Description: What the Script does
 *
 *	Creator: Unknown
 *	Maintainer: blckfire
 *	Email: blckfire@gmail.com
 *
 *
 *	Changelog:
 *	14/06/2015	- Some change
 *
 *
 *
 *
 *	Function List:
 *
 */

Code: Select all

 Includes
 /*
 *	File: includename.inc
 *
 * Version: 1.0
 *
 *	Description: General description of the includes content
 *
 *	Creator: Unknown
 *	Maintainer: blckfire
 *	Email: blckfire@gmail.com
 *
 * Dependencies: modules and includes the functions are dependent.
 * 					so that you include them in the script file that uses this include
 *
 *
 *
 *	Changelog:
 *	14/06/2015	- Some change
 *
 *
 *
 *
 *	Function List:
 *
 */

Code: Select all

Functions
/*
 *	Function: FunctionName
 *
 *	Description: What the function does
 *
 * Parameters
 *
 *
 *
 *
 *	Returns
 *
 *
 *
 *
 */
 
These are basically headers to be put and used before each of the categories mentioned they help you keep track of what's inside your files and of the changes made to them it also makes it easier for someone to understand what's the purpose of your function, script or include file.

These code snippets are based on some of the scripts from the the POL99 distro but I changed some things to comply with my way of coding.

I hope this will help whoever reads this to write more organized and readable code for generations to come. ;)

Post Reply