OXP Development Best Practices

[PhantorGorth]

This thread is for discussing best practice in scripting and OXP development in general. The aim is that the results of this discussion get migrated to the  wiki in a clear and central location so that OXP developers have a single resource for:

• How to layout scripts and plists for easier reading and debugging.
• Basic dos and don't.
• Efficient programming techniques.
• Applying Oolite specific methods that improve OXPs.
• Creating compatibility between OXPs.
• Reusing other OXP resources to prevent remaking the wheel.

Hopefully this thread will be made sticky.

Edit: 21/7/12 added from this post:

Additional topics:

• Correct packing of the OXP. Including documentation and Change Logs files.
• Version numbering.
• Licensing & copyrights.
• Documentation writing.
• Wiki entries for OXP.

[PhantorGorth]

Well the first thing we have is from this post from Ahruman:

After browsing through those examples, I don’t see anything they’re consistently doing differently from the built-in scripts other than bad habits:

• Most of them aren’t using strict mode ("use strict"; at the top of the file). This means slower code and less bug checking.
• Many scripts fail to make use of spacing, comments and consistent indentation to keep the code readable.
• There are a great deal of custom functions which are not differentiated from callbacks used by the game. Our recommendation is that internal script functions have names beginning with _ or $.

Moderator: added documentation link for strict mode

[SandJ]

.....

[Wildeblood]

- the don't-use-Notepad issue (which I cannot replicate for some reason)

Probably because it's just a myth. Microsoft adopted unicode with Windows XP - if you're still using Windows 98, go away.

- case sensitivity in file names in Linux;
- the fussiness of Macs around ";" usage;

Inferior file-name parsing in non-unix-derived OSes.
Inferior property list parsing in non-Mac OSes.

[SandJ]

.....

[Wildeblood]

- the don't-use-Notepad issue (which I cannot replicate for some reason)

Probably because it's just a myth. Microsoft adopted unicode with Windows XP - if you're still using Windows 98, go away.

I'm writing this on a PC running Windows ME. Do I have to go away?

No. ME would have been the best OS Microsoft ever made (if not for the glaring omission of unicode). It's bad reputation is very much undeserved, and caused by people who didn't configure it well. Apart from the adoption of unicode it's been downhill ever since.

The Notepad thing really is a myth, based I guess on previous versions of notepad defaulting to using some Microsoft code-page that causes apps expecting UTF-8 to choke.

- case sensitivity in file names in Linux;
- the fussiness of Macs around ";" usage;

Inferior file-name parsing in non-unix-derived OSes.
Inferior property list parsing in non-Mac OSes.

If we're going to have a Holy OpSys War, shouldn't we start a new thread forum?

I'm not interested in OSes; my point is merely that just because you're in the minority, doesn't mean you're wrong.

Addendum: two of these issues are related - the UTF-8 thing and the MAC parsing of property lists both stem from property lists originally being an XML format, so a .plist file is still supposed to follow the rules of XML even if it's not.

[JensAyton]

Can we please not have discussions of operating system and what the Right Thing is here? They contribute nothing.

Addendum: two of these issues are related - the UTF-8 thing and the MAC parsing of property lists both stem from property lists originally being an XML format, so a .plist file is still supposed to follow the rules of XML even if it's not.

This isn’t true; the OpenStep format, which is based (loosely) on C syntax, predates both XML and Unicode.

The details of what will be accepted in OpenStep format plists varies between GNUstep and different versions of Mac OS X but correct syntax, which works in all cases, is:

• Arrays are enclosed in parentheses – ( ) – and have commas between items, so there is no comma after the last one.
• Dictionaries are enclosed in braces – { } – and have semicolons after each pair, including the last one.

This is correctly documented on  the wiki, although the structure of the article isn’t really very helpful. It would probably be better to split off sections for OpenStep and XML syntax.

[Pleb]

Am I right in thinking that OpenStep is the prefered way of laying out plist files? I have noticed that most OXPs seem to use this "style" of laying out the contents of the file as opposed to the XML "style". I myself have just converted the remaining files in my Taxi Galactica OXP to OpenStep, as well as fixing flaws in the script that were previously pointed out so that it conforms to the stock scripts layout.

[Smivs]

I believe it is, although I couldn't find mention of this on the wiki when I looked, although it is there somewhere.
Certainly the core plists were all converted to openstep some time ago and I for one much prefer it to XML for many reasons, not least of which are that it's easy to read and therefore to debug, and it's a lot shorter - an openstep plist is half the length of an XML one.
Indeed I feel this thread (and eventual wiki page) should urge those using other OXPs as templates to choose a modern one using openstep over an old XML one. Indeed I even know of at least one ship OXP which uses a mix of both formats - how confusing is that!

[Eric Walch]

Am I right in thinking that OpenStep is the prefered way of laying out plist files?

When you have to edit plist with a text editor, it is easier when using openStep. So, I would think that it will be preferable for most users. For Oolite itself it does not matter which type you use. In the past I already removed several XML versions of code from the wiki and I think they should all be converted there, except for the page that deals with the difference between those two.
Only mac users have easy access to plist editors and when using that editor, it really does not matter what you use because, when viewed in the plist-editor, both versions look the same. Advantage of using the plist editor is that you can't make syntax errors But, for the sake of window and linux users, save it in openstep format. (save as: 'Text Property List')

[JensAyton]

I recommend OpenStep format for legibility. However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.

[Eric Walch]

However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.

That should only affect Mac tiger systems. And I wonder how many there are currently around. Look in Oolites own descriptions.plist at the end of the planet descriptions strings at current trunk line 403. I looked back, that error is there since is was converted from XML. No user complained. Probably they assumed Oolite would not run on tiger.

[Pleb]

Okay thanks people, I assumed this was the case. And as a Windows XP user, I just use notepad++ for all my Oolite scripting, as I find its one of the best text editors available on the platform. Are there any tutorials or guidelines when converting XML to OpenStep? I have successfully converted all of the files in my OXP now, but I had to exclude the Frigate from the Galactic Navy OXP as this was written in XML and I have not been able to convert the flashers into OpenStep format, and without them the ship does not look complete...

[JensAyton]

However, as a special recommendation, if you do use Property List Editor (or Xcode 4) on Mac OS X, use XML format, because they write invalid OpenStep plists.

That should only affect Mac tiger systems. And I wonder how many there are currently around. Look in Oolites own descriptions.plist at the end of the planet descriptions strings at current trunk line 403. I looked back, that error is there since is was converted from XML. No user complained. Probably they assumed Oolite would not run on tiger.

Hah. Well, it doesn’t in trunk. I seem to recall there were complaints. :-) Still, correct syntax is the place to be.

[JensAyton]

I have successfully converted all of the files in my OXP now, but I had to exclude the Frigate from the Galactic Navy OXP as this was written in XML and I have not been able to convert the flashers into OpenStep format, and without them the ship does not look complete... :(

Unless you’re using modernized subentity declarations, that would look something like <key>subentities</key><array><string>*FLASHER* bla bla</string><string>*FLASHER* bla bla</string></array>. In OpenStepese, that’s subentities = ("*FLASHER* bla bla", "*FLASHER* bla bla");.