Coding guidelines

Contents 1 Introduction 2 Coding style 3 Variable definitions 4 Use message(), not print() 5 Comment your code 6 Write a Readme entry

Introduction

OpenKore is written in Perl, a scripting language. Although Perl is a fine language, due to the language's extreme flexibility, many developers (including Kura, the original author of Kore, and many modders) make coding mistakes. The goal of this document is to inform developers about how to properly write code for OpenKore.

Coding style

• Use Tabs, not spaces.
• Put the bracket immediately after a statement or subroutine definition.
• Use camel case naming style for functions and variables. This means that:
  • Start with a lowercase character.
  • Use uppercase characters to mark the beginning of each word, except the first one.
  Examples of camel case names:

  createFile()
  attackMonster()
  $superWeapon

• Do not put a space between a function name and the argument list. Correct example:

  sub fooBar {
      my $canProceed = $_[0];
  
      if ($canProceed) {
          bar(1);
      } else {
          bar(0);
      }
  }

  Wrong example:

  sub
  FooBar()
  {
      my $CanProceed = $_[0];
      if ($CanProceed)
          { bar(1); }
      else
      {
          bar(0);
      }
  }
  

Variable definitions

If the variable is only used temporary (only within one function or statement), make the variable local by defining it with "my". Example:

sub foo {
    ...

    # Defines multiple local variables:
    my ($switch, $msg);

    $msg = "01";
    $switch = "ABCD";

    if ($switch eq "ABCD") {
        my $level = unpack("S1", substr($msg, 0, 2));
        message "/me uses Dummy Skill lv $level\n";
    }
}

Use message(), not print()

See the Log.pm for more information.

Comment your code

Comments are important and often underestimated. In the long run, good comments will help you and potential contributors.

• Write a brief description for complex or confusing blocks of code. Example:

   } elsif ($switch eq "DEFG") {
       # Someone used SuperBlessing lv 99 on you. All your stats
       # are boosted by +99. Take advantage of this while we
       # still can.
       # (describe algorithm if you're doing something really
       #  complex)
  
       ...
       (hundreds of lines follow)
       ...

• You should put a comment before every function definition, describing what the function does, what parameters it accepts, and the function's return value. If the function's complex, add an example. The comment should start with a "##". This allows makedoc.pl to automatically generate HTML for the documentation. Take a look at various places in the OpenKore source code for examples.

Write a Readme entry

In Readme.txt, you write down a brief, high-level overview of changes. Readme.txt is intended for users, who want to read what has changed in each release. You should also write down new config options so users can update their config files correctly.