This is some simple advice for all the “Casual Coders” out there, the ones who don’t think of writing up a bit of Javascript or a simple PHP-based app as software development: Keep releasing your work to the world, we love it, really we do, but the software world has certain ways of doing things, and it would be nice if you followed a few of the existing conventions…
Use version numbers in the name: Too many people put things out and don’t use a version number. Or they just call it “Foocode” and eventually release “Foocode 2.0” but the first one is still just “Foocode” – so start early, and apply that 1.0 version to the first release.
Use version numbers in the file name: I don’t want to download “foocode.zip” I want to download “foocode-1.0.zip” – get that version number in the file name! This will help not only the people who download your code, but will help you in the future. There is reason software uses version numbers.
Put it in a folder: I’ve learned over the years that if I package something up, it goes into it’s own directory first. I can’t tell you how many times in recent years I’ve unzipped something, and end up with 20+ files scattered all over the directory I’m in. Maybe this is just a zip thing, as tarballs always seem to be in their own directory. Nowadays I put every single zip file into a temp directory before unzipping it, as I never know what will happen.
Include meta-info: Even if you are just releasing a Javascript gallery, you might consider including a few extra files, like README and INSTALL, and LICENSE, that clearly outline things like: basic information on the author, what the software does, how to install it, what license it is released under.
Include a license: Please include information on how the software can be used. Even if this is just some cool little PHP hack you came up with, make clear what people can do with it. Can it be used for commercial purposes? Do you care if people take your code, modify it, and then release it? I know this takes some thought, but it’s better to do it up front.
Make it permanent: When you release software, you are making a commitment. If people actually use the software, they may come to rely on you for certain things. The stuff I’ve released hasn’t required me to support any amount of uses worth mentioning, but I still do one very important thing, give my software a home that doesn’t change. Pick a URL and stick with it. I can’t tell you how many times I’ve tried to go to the page where I got something, and see that the person redesigned their site, or switched blogging packages, and the software I once got from them is now ether 404’d or takes me 10 minutes of searching to track down. Of course there are the occasional folks who completely disappear from the net and taken their code with them, those always hurt a little. (If they had released their software with the right license, or used something like Sourceforge, we’d have less to worry about.)
Ok, I’m out of ideas for now. I’m sure there are a ton more, but these are just a few that have bothered me recently. Got any tips to share?