script cleanup/scripting standards proposal
Posted: 04 Aug 2011, 07:59
I would like to see some feedback, particularly regarding anything that I have missed.
Much of this is useful immediately, but some bits are designed to make porting to my (eventual) new scripting engine more painless
Personally, I dislike code like:
and
because it makes it hard to grep,
but in the (additional) case of delitem I can see why it would be wanted since it must be checked-for first ...
Much of this is useful immediately, but some bits are designed to make porting to my (eventual) new scripting engine more painless
- indentation with 4 spaces
- no trailing whitespace
- in every file, document every variable as one of:
- account variable (prefix #)
(note that there are also ## variable but they don't work in the stable version of the server;) - permanent player variable (no prefix)
- temporary player variable (prefix @) - used after the script close;s or end;s.
- dynamic player variable (prefix @) - passed into or out of callsub or callfunc
- lexical (local) player variable (prefix @) - used only within the function
(scripthelp.txt documents that ".@" means this but I don't know if that works) - local constant (prefix @) - not dependent on the player, used only within the function.
e.g. lots of @QUEST_FOO_{SHIFT,MASK} - global permanent variable (prefix $) (I'm not sure if we have any of these right now)
- npc permanent variable (prefix $) same as above but only used by one NPC
- global temporary variable (prefix $@)
- npc temporary variable (prefix $@) same as above but only used by one NPC, scripthelp.txt mentions prefix "." but I don't know if that works
- special variable (in db/const.txt with a 1 following)
- global constant (in const.txt)
- account variable (prefix #)
- Check for troublesome arrays
A troublesome array is defined as an array that is not- initialized all at once
- initialized by appending elements to the end, for use in a menu
- Set dynamic and local @variables to 0 before close;
- Remove unnecessary next;
- Remove redundant code such as end; after close;
- remove break; instead use end; (requires changing the java converter)
- Replace monsters.txt with _mobs.txt except in special cases.
- A standard for whitespace and comments.
- I have begun to use "^// " lines to be commented out code (because that is what my editor uses automatically to disable code), maybe "^///" lines for documentation? leaving "^//[^ /]" for "other". Documentation should maybe have doxygen-like tags?
- I dislike boxed comments.
- newline before every label
- no newline after label
- newline between if (condition) and conditional_command; ?
- limit line length? (break long strings using + concatentation)
- One NPC per file, except for "flavor" NPCs that only say a single line
- capitalization of temporary variable names and labels?
- An unused line after the closing '}'? I found this useful while stepping through the debugger ... maybe it could be something dual-use, such as a comment saying "end of npc Foo"?
- use checkweight("item", amount) instead of comparing against 100 items in inventory (edit because I didn't notice the bbcode error earlier - this may fall in the "higher-level concerns" category)
- Follow this list for all new script files
- Create these changes (in a separate patch) when making changes to an existing script
- Gradually apply these changes across the whole set of script files.
Personally, I dislike code like:
Code: Select all
set @reward, 500;
set Zeny, Zeny+@reward
Code: Select all
set @reward_amount, 3;
getitem "reward", @reward_amount
but in the (additional) case of delitem I can see why it would be wanted since it must be checked-for first ...