Wednesday, August 3, 2011

Being a Good SketchUp Ruby Citizen

In the world of Ruby scripts, keep in mind that users who will install your SketchUp plugin probably have installed other SketchUp plugins, too. Since Ruby is a wide-open language that lets you override and inspect just about anything, this can lead to bugs where your plugin conflicts with someone else's.

So before you distribute your hot new plugin, don't forget to follow these important steps:
  1. Try to know what others are doing/have done. This isn't always easy, but some research and questions go a long way in avoiding conflicting class/method names. It can also prevent you from duplicating someone else's effort - why re-create method x when it's already been written? Just tap into it and go (with permission, of course). Look for public scripts that are doing similar things to what you're acconplishing, and consider working with that author to cross-promote your tools. Sometimes, the already-written code won't do exactly what you want. In that case, you can either subclass yours and modify the methods (for classes, obviously), or write your own using a different class/method name.

  2. Try to use unique names rather than common ones. For example, if you write a "ProgressBar" class, you will cause conflicts with any other "ProgressBar" class. That will make for unhappy users, as they try to get tech support for something the author says works just fine on his machine, but clearly won't work on their machine; and will make for unhappy fellow developers, who have to hunt down the conflicting script, locate the author, and try to work out a solution. Better to do something like "mskp_ProgressBar" which is unlikely to collide.

  3. Encapsulate methods in a Module or a Class. Within a class, you don't have to worry about method naming conflicts, and within a module, you can be less careful about both class and method names.

  4. Test your work against as many other works as possible, and test them against yours. Unfortunately, the burden of compatibility will more than likely fall to the second developer. However, if you send your script to other developers asking them to test for compatibility with their works, they'll most likely be happy to oblige (subject to their own time constraints, naturally). This will help keep the user experience (and your reputation) positive.

  5. Be respectful of the Plugins directory structure. If your plugins has a lot of support files (piles of .rb files, html file, image files, etc.), group them together into a subdirectory under the Plugins folder. This will make it easy for users to identify (and potentially uninstall) your script. It will also make it less likely that your "cursor.png" will by overwritten by someone else's "cursor.png".

  6. Document your code and include contact information. Write generous comments and include a header block at the top of your scripts that tells people what is included with your Plugin, what it does, and how to contact you in case of upgrades or bug reports.

Thanks for Rick Wilson for the original post that I took these tips from. Code on!

No comments: