Polish Your Application

SoftPolish™ - a quality checker to help put the shining touch on your application

By Jörg Langowski, MacTutor Regular Contributing Author

No, contrary to what you might think, looking at my family name and my involvement with Forth, I’m not writing about how to translate your favorite C++ program into reversed Polish notation. This time we pronounce ‘polish’ with a short ‘o’ like in ‘soft’. Language Systems, the guys who brought you LS Fortran for MPW, have just recently started to ship SoftPolish, a software quality improvement tool that helps you put the last shining touch on your - almost - ready to go application. I received an evaluation copy and want to tell you my impressions.

SoftPolish is, as I said, a tool. I just read a letter in the July issue complaining about the tools’ reviews which we have regularly (and about the needlessness of Fortran and Forth, for that matter, so I have to answer to this one). What after all do we program the Macintosh for? For our own pleasure, that’s for sure, but many of us make real money developing and selling programs, or writing programs that help them doing some other job, like treating data. Now, you can write programs for fun and be content if that great idea of a new sorting algorithm or a hack around the Launch trap or that fast 3-D plotting routine really works. But no one (or only a few good friends) will listen to your well-deserved enthusiasm or even use your program when a) you can’t explain (Xplain?) to them how to use it and b) they can’t use it without your continuing help because of illogical behavior or -worse - ‘undocumented features’ (no, NO!!! don’t double-click the mouse outside that window, you’ll destroy your hard disk!!!! oh well too late.). This is speaking of my own experience, so let’s hear it for good documentation and well-thought out and bug-free user interfaces. Not that I’m writing any of that stuff for MY programs. I did it once, for something that I distributed to a number of people, and in a very imperfect way. Still it took a lot of time, and I admire those who have the patience to create a perfectly looking, logical, easy to use interface to their original software idea and then give it away or sell it at cost. In my own field, the genetic data editing package DNA Strider comes to mind, or the desk accessory editor McSink (now Vantage, a commercial product).

Anyway, SoftPolish is a program that helps you to create a user interface that doesn’t confuse the user, or pull the rug under his feet because you forget to put some necessary resources into your application and that didn’t show up during testing.

How SoftPolish works

SoftPolish checks three major aspects of a Macintosh application:

• the consistency of the user interface;

• the validity of resources, their types and numbers;

• the spelling of strings anywhere in the program (dialogs and alerts, STR, STR# resources, file and folder names, etc.).

To see what SoftPolish does, let’s go through the example that is given with the disk. There is an application ‘Testapp’ created with AppMaker, which contains several deliberate errors.

When you start SoftPolish, it comes up with a ‘Navigator window’, like a modeless dialog box. Here, you can choose one of six functions (which are also accessible through the menus): Choose Target, Build User Dictionary, Scan Target, Correct Spelling, Clean up, and Help.

You have to choose a target first, so you click the corresponding box, you select the application to ‘polish’ from a standard file dialog, and then you may start by clicking ‘Scan Target’. The User Interface Police then starts to scan all resources of the application. The following checks can be made:

• Are the menu command key equivalents correct, i.e., are any characters used in duplicate, or used in a way not recommended by the Apple Human Interface Guidelines?

• Are the menu titles correctly capitalized? (i.e., a menu or window title starting with a lower case letter is not recommended)?

• Do the dialogs and menus fit on a small screen (PowerBook or Macintosh Classic)?

• Is the space for dialog text items large enough to contain all the text (such problems may occur after an application has been localized for a different language)?

• Do all dialog items fit inside the dialog box, are they non-overlapping, not too small or too big, and is there enough space between them and the dialog border?

• ‘Old style’ quotation marks like the ones I use all the time (',") are flagged because they should be replaced by the “new style” (“,”,‘,’). So are ellipses ( ) that are made out of three periods in a row (. . .).

• Word and sentence spacing are checked; you should not use two spaces between words, or after a period.

• Are any resource numbers used that are reserved by Apple? Are there any resource types which are lower-case only (that’s also reserved)?

• The internal consistency of resources is checked.

• Any resources which should have a fixed size (like an ICON) are flagged if their actual size is different.

• ALRTs, DLOGs and DITLs are cross-checked to make sure the resources referred to in another resource are present.

• All strings in the application (STR#, STR, DITL, file and folder names etc.) are checked for correct spelling. An English dictionary is included; I also received a French dictionary in my evaluation copy, and there are dictionaries available for other languages (Dutch, French, French Canadian, German, Italian, Norwegian, Portuguese, Spanish, Swedish, and U.K. English at $49 each). You can build your own user dictionary for technical terms not included in the main dictionary.

While the scan is running, a log is written to a text window which you can review after the scan, and save or print.

SoftPolice - sorry, SoftPolish - will also make some of the necessary changes to your application if you tell it to do so. Misspelled words can be corrected - like in any good spelling checker, alternatives are suggested - and you can define a list of unwanted resources that you want to be removed. For instance, some resources might be left over from testing and are not needed in the final application. The modification and creation dates will also be set to any value you like. Any inconsistencies found in resource numbering or dialog layout will, of course, have to be corrected by the programmer.

Documentation

The 50-page manual is of the usual quality you’d expect from Language Systems when you know their Fortran manual. The various options of the program are described very clearly, and a tutorial is provided that lets you test some of SoftPolish’s features on a test application. All the important information from the manual is also repeated in a Help window that you can call it up.

I’ll show you some examples of the types of errors flagged in the test application:

1. Multiple spaces in About box:

yields the following error message:

  DITL 1 <Item #2> “About” 

The user interface was created with AppMaker, then AppMaker generated the source code.

  •• Multiple spaces between words

The next dialog contains several errors:

DITL 130 <Item #1> “Mistake” 
    cancel
  •• Should the word start with a capital letter?

  DITL 130 <Item #2> “Mistake” 
    This Check box will not fit in this dialog
  •• Space is not wide enough for the text

  DITL 130 <Item #3> “Mistake” 
    This  Item   is  Spaced.   Out
  •• Multiple spaces between words

  DITL 130 <Item #4> “Mistake” 
    This item is Mspelled
  •• Questionable spelling: Mspelled

  DLOG 130 “Mistake” 
  •• DITL 130 item 2 is within 6 pixels of the edge of the window
  •• DITL 130 item 3 is within 6 pixels of the edge of the window
  •• DITL 130 item 4 is within 6 pixels of the edge of the window

The last dialog box will definitely create a problem for a Mac Plus or Classic user and SoftPolish complains at once:

  DLOG 129 “Problems” 
  •• The window is too wide to fit on 9” screens

  DITL 129 <Item #3> “Problems” 

This is a poorly desined dialog box. It definitely will not fit on a small screen!

  •• Questionable spelling: desined

  DITL 129 <Item #9> “Problems” 
    TestApp’s comment
  •• Should this be a real apostrophe (’)?

  DITL 129 “Problems” 
  •• PICT 128 needed by DITL 129 item 4 is missing!

There are many more errors which are flagged in this program by SoftPolish. Actually, it becomes annoying to see all of them and you really feel you have the User Interface Squad on your back. But I think it is of great help to developers in the final steps of creating a new program, it should remove many errors which may otherwise be detected only after months of testing (i.e., alert boxes which are presented only for very rare errors).

Aside from the spelling checker, an absolute necessity looking at some of the existing applications, I especially like the option which cross-checks whether all resources referenced in a dialog are actually present, and the size checks on dialog boxes and dialog items. The only negative thing about SoftPolish may be its rather steep price - $295 suggested - but mail order sources might offer it cheaper. [Check the MacTutor Mail Order Store for a special of $169 until October 31, 1992. - Ed.]. An individual developer will probably think twice before spending 300 bucks for a tool which is used much less often than for instance his C compiler which is in the same price range.

User customization

When I just wanted to send off my column, I received two tech notes from Language Systems (which they actually had announced to me before). They describe how you can modify the resource checking process to adapt it to your own specifications (i.e., play legislator to the User Police).

First, there are two resources that you can modify which specify all the minimum and maximum sizes of buttons, check boxes, how far away from the border a dialog item has to be, the dimensions of small screens, etc., etc. You can change all these numbers, of course.

The most important feature, however, is that you can add your own resource-checking code for resource types that are not checked by SoftPolish by default. Plug-in code modules, state of the art of today’s software technology (by the way, I’m anxious to see the dynamically linked libraries announced by Apple).

An excerpt from the tech note explains best how the user module mechanism works:

“When added to SoftPolish, stand-alone code modules can provide extra functionality for testing custom resources. Each code module must have a resource of type ‘SPCM’. The name of the ‘SPCM’ resource indicates what resource type the code module accepts. For example, an ‘SPCM’ resource named “DITL” is, to SoftPolish, a code module that handles ‘DITL’ resources. If you add a code module for a type SoftPolish already tests, your code module replaces the internal SoftPolish handling of that resource type.

Code modules are called by the SoftPolish application which passes the address of a parameter block. This block contains information the code module must know about the resource. It also contains mechanisms, or “callbacks”, that call service routines within SoftPolish. Language Systems supplies header files that define the parameter block in C, Pascal, and FORTRAN.

The parameter block is divided into three general areas: the header, callback information, and SoftPolish info. The header contains the handle to the resource to be tested and other useful reference information. Callback information consists of the fields a code module uses to request SoftPolish services. In normal use, code modules should change only the fields in this section. The last area, SoftPolish information, consists of the fields SoftPolish uses to pass information to the code module.

The general programming style for code modules is to first check which tests are currently requested and then make the callbacks to perform these tests.”

Pretty clever - a good example of how an extensible application should be written. For that matter, it is regrettable that not all applications have some extension mechanism built in.

Fortran news - Absoft

Unfortunately we have a delay between writing an article and its publication. It is quite short, 6-8 weeks, but sufficient that the activities of dynamic enterprises like the developers of Fortran for the Macintosh can make our reviews outdated when they appear. I just received a copy of an E-mail that Absoft sent to my colleague, Alan Hewat:

Tuesday, July 28, 1992

Dr. Hewat:

1: Unfortunately, I cannot help you (today) with AppleEvents. We don't have any examples ready for release yet. However, the next release of the compiler will include full AppleEvents capability and include much example code. We haven’t set a release date yet.

2: You are correct that Absoft does not accept Internet mail through AppleLink. Cost was not really a factor in the decision; there are easier and more direct ways to reach us. AppleLink users can send mail to “absoft”; Internet users can contact me directly: “ldr@absoft.com”.

We haven’t been using the Internet address for Mac tech support until recently; that’s why it has not been widely publicized. Eventually we will probably replace my individual address with a more generic “tech support” address.

3: Please express my appreciation to your colleague J. Langowski for pointing out some shortcomings in our documentation. A review of LS FORTRAN 3.0b (which he wrote some time ago, but which was only recently published here) incorrectly claimed that Absoft MacFortran II could not pass the Paranoia accuracy test.

But he cannot be held accountable for the error. After reading his remarks, we concluded our manual and example code do not adequately discuss the issue of FPU math versus strict IEEE compliance. We’ve always been able to pass Paranoia, going back to MacFortran/MPW 1.0; as long as you set the rounding precision of the FPU appropriately. But we’re going to start documenting more clearly how to do this and under what conditions it would be necessary.

If you or your colleague have any questions on this or other technical matters, please feel free to contact me.

Lee David Rimar

Thank you very much for these remarks. I thought with the last article that I wrote the question of accuracy vs. speed in Absoft Fortran was resolved (i.e., when you give up the speed advantage over LS Fortran, you gain back the accuracy); but I might still be wrong if there are some other non-documented options to set the rounding precision of the FPU. I look forward to seeing some newer examples by Absoft, and especially the new AppleEvents-aware compiler. You’ll hear about it.