Hints and Tips on writing good software

Following this check list will make your software more appealing to users. If you are writing Shareware this is absolutely vital, but even if it's PD why not make it as good as you can? This doesn't normally take any more effort than doing it badly, and you won't look back in the years to come and cringe.

• Make sure it's classified properly.
  • A Shareware program is one which may be freely distributed but which is Copyright material and which requires a user to send a Registration Fee to the Author if he/she wishes to continue to use the program. To qualify as Shareware a program must not be severely restricted in any way and must contain proper documentation. If any major functions are disabled or if the program is supplied without proper instructions then it's not Shareware, it's just another crippled commercial demo or Crippleware. I'm a member of the Association of Shareware Professionals (the ASP) and so I take Shareware very seriously.
  • A Public Domain program is one to which the Author has renounced all rights and which has been placed in the Public Domain. By it's nature such a program may not have any restrictions placed upon its use or copying by anyone.
  • A Freeware program is one which may be freely copied and distributed but to which the Author still retains copyright. If a program description contains something like 'This program is Public Domain but you must not.....' then it isn't PD (whatever it says), it's Freeware.

  One final catagory which deserves a special mention is GPL or General Public Licence, often called GNU, and administered by the Free Software Foundation. This is frequently misunderstood system, often by the people who realease software and say it's released under GPL, so I'll explain a bit more about it later.

• Make sure it works! Unless you are absolutely certain of what you are doing use standard RISC OS routines to ensure that your program will work correctly on all types of computer.
• Try to make sure that your program will function on different filing systems. Most people won't put up with a program which only works from a floppy disk in drive :0 and will want it to run from a hard disk. Programs which only function on ADFS and not IDE or SCSI or which won't run from archives can be a pain. never *MOUNT a disc, there is always a better way. Don't upset users by using the *DIR command and leaving them logged on to a CD disc!
• If it's a desktop program try to ensure it will work in as many different screen modes and monitor types as possible. Similarly if your program operates outside the desktop but returns to it make sure that you restore the original screen mode, system font and palette when you return if you have changed them.
• If you are writing a game make sure that there is a 'way out'. With some games the only way to stop is to press the Reset button. If you write a program like that you are going to have a lot of disgruntled users if they've forgotten to save something first. There should be a simple way to quit, and the user should be told how to. It's no good saying afterwards that you only need to press 'Q' to quit. People expect this sort of thing to be made plain before they start.
• If your program is Shareware remember that it's your job to tell the user the program is Shareware and to make sure that he/she understands that they are obliged to register and exactly how to do it. I know of one Shareware author who has just included an email address. Think about it. People without internet access can't register, and people with internet access can't just send payment by email because he doesn't accept credit cards. Not only that, but six months later he changed ISP and the email address was no longer valid. The idea is to make it easy and attractive for people to register, not put obstacles in their way.
• Make sure your program is complete. If it uses any third party modules (other than standard items like the Toolbox) such as Interface, ABC Basic, etc. then ensure these are included. Don't just RMload them from !System.Modules - not everyone will have a copy in their !System directory.
• If your program is written in machine code or a compiled language then, if it's PD, it would be nice if you included the source code. It is often very useful to someone who is learning a language like 'C' to be able to see how other people do things. Including the source code (or an 'un-crunched' version if it's Basic) allows users to modify the program to suit their own personal needs and often extra features are added in this way and fed back to the Author.
• It is an advantage for libraries to be able to distribute programs in archived format and programs which won't run directly from an archive like ArcFS are at a disadvantage. If your program won't fit on an 800K disc when de-arc'ed then people with older models and no hard drive (ie. the most impoverished users) won't be able to use it. Quite often it is possible to split a program over two 800K floppies with a bit of forethought and a couple of OS variables.
• Ideally a program should run on the lowest common denominator machine, ie. a 1Mb ARM2 with a single 800K disc drive, no hard disc and any version of RISC OS. In fact, the 'bottom end' machine is now more realistically regarded as an ARM 2.5 with RISC OS 3.1 and 4Mb RAM and for 'serious' users a RPC 600 or A7000 with 8Mb (which means a hard drive). Obviously some programs will need more than this and that's perfectly OK as long as it's made clear.
• If your program will only work on certain versions of RISC OS please say so clearly. It's not unreasonable to expect most 'simple' programs to work on all versions of RISC OS from 3.1 and to be RiscPC and Strong ARM compatible. Obviously some would not be expected to work on everything (eg. a program that was designed to add features to the RiscPC wouldn't be expected to work with RO 3.1)
• Remember that if you introduce 'banner' screens on a Shareware program which are intended to annoy people who use your program without paying then they will also annoy people who are trying the program and who DO intend to pay. I don't approve of this type of 'Nagware', and anyway it's counter-productive. Anyone dumb enough to seriously annoy a prospective customer doesn't deserve any registrations. Up to 2 banners per session (ie. on loading and quitting), each lasting not more than about 5 seconds is OK. Much more than this and it becomes really aggravating and counter productive.
• Like most people, I like some sort of documetation. I certainly won't allow APDL to be associated with a Shareware program which has about twenty lines of explanation and then says '100 page laser printed manual available upon registration'. I would regard any such program as crippled. Anyway, how can a prospective purchaser evaluate it if there are no instructions, stupid!!.
• Interactive help isn't sufficient unless your program is very simple. Documentation should be a document. It should be readable by people without DTP software such as Impression, and printable too. If it's big enough, it's best laid out like a book, with page numbers, contents and an index. Some people like StrongHelp or other hypertext programs. Well, it's alright as an extra, but it's not really enough on its own. OK, you can get away with this if it's a PD program (people will think you're either illiterate or just lazy) but if it's Shareware you've possibly just lost another sale! HTML is now a viable alternative for on-disc documentation as it's not unreasonable to assume that everyone will have access to a browser and the text can be printed (or turned into bare text with a program like !UnHTML)
• While on the subject of instructions I have noticed that the thing most commonly missing is a description of what the program actually does!. It's amazing how often I find a long, complex, !Help file, but nowhere does it say what the program's for. At the beginning of the instructions you should put a (short!) section describing the program's uses and features, and any special considerations, ie. what machines it will/won't work on. Give a short list of it's features. It's up to you to tell a prospective user (and purchaser if it's Shareware) how incredibly useful and wonderful it is. If you don't tell them (quickly - before they get bored) they won't bother to try it.
• If your program is Shareware spend hours on the design and layout of your windows. They are your shop-window, the bit the user sees most. Time spent making them easy and pleasant to use will be well worth it. Don't forget that although you might have a RiscPC and use Homerton font on the desktop a lot of users will still be using the system font (and visa versa), so make sure text won't be 'clipped'. (Upper case text in Homerton is about 25% longer than the System font, lower case about 25% shorter, and anyone with a new type machine who doesn't bother to check using something like !FontSwap is an idiot). Also, I hate pane windows. The RISC OS desktop is much more flexible than a certain other inferior system from which the idea was borrowed, and your users won't want to have to scroll up and down in some fiddly little pane window stuck in the middle of a 1280 x 1024 desktop. If you want to see how not to do it look at some commercial programs (eg. Impression Publisher). People who buy commercial software have to put up with what they've been given because they've already paid 'up front'. With Shareware they don't pay until after they've used the program, so the design and layout of your windows must make them pleasant and easy to use.

How to Lose Your Credibility as a Decent Programmer in Twelve Easy Steps

1. Use MemAlloc under RISC OS 3.
2. Reduce the font cache to 0, especially on a RiscPC which uses fonts everywhere. In fact, reduce everything, even if you don't have to. After all, I'm sure your user only configured that RAM disc by accident, and didn't really want that much in the sprite area.
3. In games, switch screenbanks, then report errors where the user can't see them. Leave them with a blank screen and no idea of what's going on. They'll love you for it.
4. Ignore filing system errors, or, even better, don't trap them so the program just crashes. I'm sure your user won't mind if they lose two hours work because the disc was write protected or they were running the program from a read-only archive or CD.
5. Use GOTOs in Basic. If there is a bug it'll make it more difficult for an educated user to fix it, but you probably don't like those know-it-alls anyway. It's also the best way to make your program run like a snail on Mogadon..
6. Alter the system sprite area. Nuke all those Memphis users!. Whatever you do don't use a private sprite area - that would mean looking at the PRM.
7. Alter the wimp sprites. Your radio icons are so cool they'll fit in with any other icons the user might have. Make sure they're lo-res too, while you're at it, just for those poor people who only have multisync monitors.
8. Do a *DIR <Obey$Dir> in your !Run file (even better, do it in your !Boot file!). It's obvious that people who do this are expert RISC OS programmers.
9. Only accept keypresses in upper case. Then show your superiority when they say "It says press Q, and I do, but nothing happens" by telling them about caps lock.
10. Use BASIC's INPUT statement so your program can laugh at the idiots entering invalid data. 'OS_ReadLine' is probably only there to fill up a few blank pages in the PRM anyway.
11. Use CLOSE #0 to close a file in BASIC so you close all files on the current filing system. If that's IDEFS and your program is running from ADFS then all programs running on IDEFS will have their files closed but yours will be left open. This is a great way to screw up everything (including your own program when it trys to open the same file again). Anyway, it's too much trouble to be bothered keeping track of what files you've opened so you can use CLOSE with a file handle!
12. Write directly to screen RAM at FD800. After all, it's always been there, hasn't it? Surely Acorn wouldn't move it now everyone knows where it is (and what's all this rubbish about OS_ReadVduVariables anyway - I never used that on my Amiga.)

The GNU General Public Licence

This explanation is obviously very brief and far from comprehensive. If you even consider writing software for release under GPL (or it's variants - there are several) then you should visit the Free Software Foundation web site and read/download the relevent Licence files. You will be bound by these, so make sure you know what you're agreeing to!

In general, the GPL is designed to allow anyone to obtain, use and modify a program but to prevent anyone from placing any more restrictions on it than it had when they obtained it, even if they have extensively modified and improved it.

Because (in general) you have the right to modify a program it is obligatory for source code to be made available. Furthermore, if someone incorporates part or all of a program released under GPL into their own work then the whole program is automatically covered by GPL, so you are obliged to release the source code of the entire program.

Naturally, because the aim is to stop anyone from removing or restricting any of the rights granted by the GPL then, if you pass on any copy of a GPL program, even if one extensively modified by you, you must also include a copy of the GPL so the recipient is fully aware of their rights. You cannot modify, remove or limit any of the rights granted to you when you received the program no matter how much work you put into improving it. That's the idea. Because each programmer stands on the shoulders of those that have gone before he/she has no right to impose any more restrictions on the program than when they received it.

What is often misunderstood is that it is perfectly OK to sell a GPL program. In fact, this is often done. What you can't do is claim any sort of copyright over it and you must also include a copy of the GPL with it. So, someone who purchased a copy could give away (or even sell) copies of the program. There is actually no contradiction here with the 'free software' nature of the GPL. If you don't want to pay you can still get it for nothing. However, a payment to a commercial distributor will usually get you 'added value' such as printed manuals, support, etc. You pays your money (or not) and takes your choice.

An example of this is Linux. This is 'open source' software, which is not quite GPL (but all GPL software is obviously open source). You can download various versions of Linux, or even get it on CD for media and P&P costs, but if you have problems you probably won't get much help; or you can buy a 'branded' distribution like Red Hat, Suse, Caldera, etc. and get huge amounts of material, (probably) printed manuals, some sort of 'easy installer', and help if you have problems.

Don't forget that by modifying, porting or improving a program, or even by including some code from a GPL program into your own program then the new program is automatically covered by the GPL. If you don't acknowledge this then you are in breech of the GPL yourself and can be prosecuted for software theft by the Free Software Foundation because you have 'stolen' material released under the GPL.