User:Void Singer/Formating

Coding Practices: Formatting

this is a listing of how I format code, for readability and self documentation, not everyone likes it, but if you use something and stick with it, others will thank you, and you'll thank yourself later when you look at it and your eyes want to glaze over thinking "WTF was I doing?"

1. variables:
   • all user variables are prefixed with "v" (for variable) [so we can quickly Id variables]
   • all variables have their type included in 3 letters (eg. vStrData) [so we know the type, saves debugging typcast problems]
   • all variables denote what they are for (eg. key vKeyOwner = llGetOwner();) [saves on comments, makes it esay to know what we're doing]
   • all States prefixed "vs" -eg vsStateName [so we can id states]
   • all user defined functions prefixed "vf" and return type -eg vfFunctionName [so we can Id functions and their return types]
   • All Globals are prefixed with "vg" (for variable-global) [makes it easy to spot globals]
   • All Constants are prefixed "c" and placed in all caps to distinguish from ll -eg cSTR_TITLE [easier to spot non ll constants, and avoid possible conflicts with new ll constants]
   • Bitmasks and booleans are given type "vBit" and "vBoo" [so we know how they are being used]
   • Vectors describing Size, Position, or Color are given as vSiz, vPos, & vCol, respectively
2. Comments: [use lots of them to help us remember/see what code is trying to do]
   • Sections/Headers: "//--// text //--//"
   • Code: " //-- the line below does X" (note the extra space indent
   • Edit/Notes: " //-- the line to the left is editable or could use changes"
3. Brackets/Whitespace:
   • Functions: space away from the container -eg. llRound( vIntNumber ); [makes it different from grouping]
   • math: always separate math -eg 2 + 2, exception increments --x, ++x [easier to read/debug]
   • Grouping: do not space inside, or out -eg. ((vIntNumber + 2) * 5) [makes it different from functions]
   • Events: follow function rules + { -eg. touch_start( integer vIntTouches ){
   • If/Loop: follows grouping rules with a space before group, and trailing { -eg if (TRUE){
   • loops, if/else, events, states, functions: "{" goes on the same line as the calling body, "}" after the last entry, and are ALWAYS used (even where optional) [for readability & debugging]

Note:
Due to disagreement about placing "{" on the same line as the originating structure, they
will be on the line following the structure for WIKI function examples... it's a matter of
personal taste and practice for me, so not a big deal =)

1. General WhiteSpace:
   • blank line between event [easier to read]
   • blank line between sections of code doing different things [groups like actions]
   • tabs are 2 spaces, to reduce wrapping for nested items. any items inside a loop, if/else, event, state, or function recieves a tab [saves wrapping, eaiser to read/debug]
2. Special Cases:
   • Bitmasks given as numbers are in uppercase hex -eg. 0xFFFFFFFF [easier to see usage]
   • Long tests/function calls: wrap each variable/container to the next line with level spacing -eg see below [easier to read, less sloppy than built in wrapping]

//--// this is an example script    //--//
//--// it has no real purpose other //--//
//--// than to show my formatting   //--//

string   cSTR_TITLE = "example script" //-- something to tell the user later
integer  vgIntTotalTouches = 0;

string vfStrFunctionExample( key vKeyOwner ){
  return llKey2Name( vKeyOwner );
}

default{
  state_entry(){
    llOwnerSay( "Hi, " + vfStrFunctionExample( llGetOwner() ) );
  }

  touch_start( integer vIntTouchCount ){
    do{
       //-- below is the example of wrapping functions parameters
      llSay( 0,
             cSTR_TITLE + " has been touched "           //-- this is an example of
                        + (string)(++vgIntTotalTouches)  //-- string wrapping, always
                        + " times" );                    //-- has + in the front
    }while (--vIntTouchCount > -1);
  }

  changed( integer vBitChanged ){
    if (vBitChanged & CHANGED_OWNER){
      state vsReset
    }
  }
}

state vsReset{
  state_entry(){
    llSay( 0, "New Owner " + vfStrFunctionExample( llGetOwner() ) + " detected; reseting" );
    llResetScript();
  }
}

Comments

Feel free to leave me a note on my User Talk page.