Sir R. M8gic1an
2010-05-30 16:11:31
Note: This thread was originally written for MSI. MSI uses standards that match the changes in standards so far discussed for SRL 5.
As we will be scripting as a group, we need a standard to script by, so we can understand each other's code, keep it clean and simple.
For this there are several steps we should take:
- Use constants, not hard coded values.
As you can see, that makes the code much more readable and understandable (except if you don't know with..do statements in this case)
This use of constants will also avoid us skimming through the files looking for the right values.
If you just use a number once, then no const is really needed as long as you comment what it is. If a number is used more than once use a const, as it will make it more readable and easier to edit in the future.
- Make function headers.
This is very important. Makes it much better looking and easier to understand, as the description avoids you having to look through the code to know what the hell the specific func/proc does.
This is how we will do it:
- Commenting
Another important thing is commenting. Our core will most likely be complex so we are able to deal with all cities and skills, so commenting will be essential. Any more complicated part should be commented to explain, anything that is not obvious should be commented and anything that is generally long and involves a lot of begin..end should be commented:
- Naming your variables
single letter vars and general non-sense names should be avoided. If the var has no purpose other than being used to loop, then a single letter is acceptable. If it has any more complex use then please give it a propper name.
As you can see, 'i', 'j' and 'TP' are non descriptive names, but they are just simply used for the loop; All other variables have a pretty self-describing name.
- No variable recycling!
It sometimes happens that you recycle variables, as in you use 'i' for a loop and then further on you need an integer for something and are no longer using 'i' so you use it there. DON'T DO THIS. It is indeed more efficient, however, it makes the code harder to understand. Remember that MSI is a project that will involve all SRL Members+ and therefore all code should be crystal clear to understand for everyone!
- Use Scar Scripting standards.
- Debugging
This will be a very important part. It is necessary to be able to track through debug what went wrong where. No need to be extreme about it, but returning the result of every function would be a good thing to do. 'In' and 'Out' of function debugs are also extremely useful.
—
That is all I can think of for now, if you have any suggestions/questions go ahead and post :) I will want to see these standards applied in every single piece of code that goes into the MSI SVN.
~RM
As we will be scripting as a group, we need a standard to script by, so we can understand each other's code, keep it clean and simple.
For this there are several steps we should take:
- Use constants, not hard coded values.
const
P_CITY = 0; //City we are in
P_LOC = 1; //Which part of the city
P_LOADS = 2: //How many loads
P_ITEM = 3; //How many of the specific item eg Iron Ore
P_XP = 4; //XP earnt
//how would we use these?
Procedure Proggy;
begin
with Players[CurrentPlayer] do
begin
{this is an example of what not to do }
writeln('City N: '+IntToStr(Integers[0]));
writeln('Loc N: '+IntToStr(Integers[1]));
writeln('Loads : '+IntToStr(Integers[2]));
{this is baaad!}
{this is how you do it}
writeln('City N: '+IntToStr(Integers[P_CITY]));
writeln('Loc N: '+IntToStr(Integers[P_LOC]));
writeln('Loads : '+IntToStr(Integers[P_LOADS]));
end;
end;
As you can see, that makes the code much more readable and understandable (except if you don't know with..do statements in this case)
This use of constants will also avoid us skimming through the files looking for the right values.
If you just use a number once, then no const is really needed as long as you comment what it is. If a number is used more than once use a const, as it will make it more readable and easier to edit in the future.
- Make function headers.
This is very important. Makes it much better looking and easier to understand, as the description avoids you having to look through the code to know what the hell the specific func/proc does.
This is how we will do it:
{*******************************************************************************
procedure FixSpells;
By: ZephyrsFury
Date: 01 Sep 09
Description: Orders the spellbook by level.
*******************************************************************************}
- Commenting
Another important thing is commenting. Our core will most likely be complex so we are able to deal with all cities and skills, so commenting will be essential. Any more complicated part should be commented to explain, anything that is not obvious should be commented and anything that is generally long and involves a lot of begin..end should be commented:
Function SetUpWalk(City, WhereTo: integer): TheWalk;
begin
case City of
City_Varrock:
begin
case WhereTo of
begin
Loc_VEM:
begin
with Result do
begin
City := City_Varrock;
Loc := Loc_VEM;
Path := [
Point(3011, 3355), Point(3008, 3345), Point(3008, 3335), Point(3008, 3325),
Point(3017, 3321), Point(3026, 3316), Point(3033, 3314)
];
end;
end; //of Loc_VEM case
Loc_NETree:
begin
with Result do
begin
City := City_Varrock;
Loc := Loc_NETree;
Path := [
Point(3011, 3355), Point(3008, 3345), Point(3008, 3335), Point(3008, 3325),
Point(3017, 3321), Point(3026, 3316), Point(3033, 3314)
];
end;
end; // of Loc_NETree
end; // of WhereTo case
end; //of City_Varrock case
end; //end of City case
end;
- Naming your variables
single letter vars and general non-sense names should be avoided. If the var has no purpose other than being used to loop, then a single letter is acceptable. If it has any more complex use then please give it a propper name.
Function WhereAmI: TheWalk;
var
i, j, Dis, Closest_Dis: integer;
TP, Pos, Closest_TP, Closest_Info: TPoint;
begin
Pos := GetMyPos;
Dis_Closest := 1000;
for i:= 0 to HowManyCities do
for j:= HowManyLocs(i) do
begin
TP := LocationPoint(i, j);
Dis := (sqr(abs(Pos.X - TP.X)) + sqr(abs(Pos.Y - TP.Y)));
if (Dis < 7) then
begin
Result := SetUpWalk(i, j);
exit;
end;
if Dis < Closest_Dis then
begin
Closest_Dis := Dis;
Closest_Info := Point(i, j)
Closest_TP := TP;
end;
end;
//if we are here, it means we are too far from any point
//therefore, we will walk to the closest
Result := SetUpWalk(Closest_Info.x, Closest_Info.y);
WalkToInvisiblePoint(Closest_TP);
//WalkToInvisiblePoint = a function that'll generate it's own path and walk there.
end;
As you can see, 'i', 'j' and 'TP' are non descriptive names, but they are just simply used for the loop; All other variables have a pretty self-describing name.
- No variable recycling!
It sometimes happens that you recycle variables, as in you use 'i' for a loop and then further on you need an integer for something and are no longer using 'i' so you use it there. DON'T DO THIS. It is indeed more efficient, however, it makes the code harder to understand. Remember that MSI is a project that will involve all SRL Members+ and therefore all code should be crystal clear to understand for everyone!
- Use Scar Scripting standards.
- Debugging
This will be a very important part. It is necessary to be able to track through debug what went wrong where. No need to be extreme about it, but returning the result of every function would be a good thing to do. 'In' and 'Out' of function debugs are also extremely useful.
—
That is all I can think of for now, if you have any suggestions/questions go ahead and post :) I will want to see these standards applied in every single piece of code that goes into the MSI SVN.
~RM