Author Topic: Want to patch or work on a Ulysses project? Use our codestyle.  (Read 6332 times)

0 Members and 1 Guest are viewing this topic.

Offline Megiddo

  • Ulysses Team Member
  • Hero Member
  • *****
  • Posts: 6185
  • Karma: 391
  • Project Lead
    • View Profile
Want to patch or work on a Ulysses project? Use our codestyle.
« on: September 21, 2008, 12:49:09 AM »
In the interest of keeping everything neat and tidy in our code, this is the code style we use...

Lots of spaces
It's much easier to read code when it's nicely spaced out. There should be spaces around operators, array braces, and function parenthesis.

Examples:
Code: Lua
  1. panel:SetSize( wide, ( buttonTall + vspacing ) * visibleRows )
Code: Lua
  1. ulx.clientMenuContents[ label ] = data

No semicolons at the end of lines
Lua doesn't require them and they clutter the code, leave 'em out.

Absolutely no usage of garry's modifications to the language
This is a must. You should not use C-style comments "//" and/or "/*...*/", and you should not use the '!', '&&', '||' operators. These were all edited into the lua engine by garry, and non-standard. This means that any code written with these must be modified to work in any other project. This is simply unacceptable.

What about the binary operators '<<', '>>', and '~'? These operators actually serve a purpose and can be useful in certain situations. First, ask if it's absolutely necessary. Is there a way to do what you want another way without making the code more complicated? If the answer is no, then you can use these operators. Otherwise, find another way.

We prefer not to put parenthesis around conditionals
C requires that you write "if (x) { ... }", but lua works with just "if x then ... end". We feel that no clarity is lost by dropping the parenthesis, and in fact improves readability when you have a lengthy conditional.

Write self-documenting code, add comments as necessary
As much as possible, try to make it apparent what's going on just by variable and function names. Add comments whenever there might be confusion as to how something works.

And most importantly...
If a rule above reduces clarity, it can be broken. These are guidelines, not laws. If you're writing a patch, conform to the code style around the changed area as much as possible.
« Last Edit: October 06, 2008, 10:59:52 AM by spbogie »
Experiencing God's grace one day at a time.