Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Writing an Application Solely in Glish Up: How to Write an AIPS++ Application Previous: Introduction

Subsections

General Interface Considerations

Before we get into the nitty-gritty of how to construct an application of either form, a few words on the interface you provide for the user are in order.

Simple interfaces

While programmers will use the interfaces you provide (real applications can be coded entirely in Glish), the primary audience is users. This means that your interfaces should emphasize simplicity, at least until there is a demand for a more capable and complicated interface.

Some of the issues we'd like you to consider are:

Try to keep the total number of member functions down. Provide only one method of obtaining some result, not multiple methods optimized for slightly different purposes.
Trade simplicity for runtime efficiency. Slow operations can always be moved into C++.
Use existing objects as much as possible. Be sparing with the use of trivial functions that simply relay methods from one object to another.
Do not use Glish defaulted arguments to simulate overloading. One function should perform one operation. For example, do not have a constructor function that can both attach an image to an existing file, or create one from a shape and a description. Use different names for these two purposes.
Prefer Glish tool methods to global functions if there are a number of related functions, even if they do not need to share any state.
If you are a programmer, ask a user for his opinion about your interface. If you are a user, ask another user for his opinion.
Documentation can cure many sins of interface design. Examples can save otherwise poor or skimpy documentation.

Naming conventions

All user-invokable Glish functions must be entirely in lower case. Internal functions and variables may be in mixed case if you prefer. Generally words are run together, however you may use underscores to separate words if you are imitating a glish builtin (e.g. writing an is_image() function that apes the builtin Glish is_record() et al.)¹. However, generally we prefer openfile() to open_file(). Generally, names should err on the side of being somewhat longer and unambiguous, however commonly typed names can be short since repetition will ensure that they are not obscure.

If you only expect one object of a type to typically exist the class name should be be a verb - imager. If you expect that more than one object of that class might be active at once it should be be a noun - table. In Glish, the most common common constuctor function should have the name of the class: mytable := table("file").

Class names will be normally be singular when the object refers to a single entity (image, table). Occasionally it might be plural if the object refers to a collection of some tye units.

You should try to use the same function names in your Glish objects that are used in other Glish objects that perform similar operations. This reduces the number of names that a user has to remember. You might break this rule however if the argument lists have to be very different in the two classes. Some names you should be aware of:

open: Attach the object to a file.
summary: Summarize the state of the object (e.g. for an image, one would provide the size, coordinate information, and the like).
display: Start a GUI browser/editor for the object.
delete: Destroy/remove/... the current object. The Glish proxy object should disable itself so that it is no longer usable .
shape: Return the length of each ``axis'' in the object.
length: Return the total number of values in the object.

Sometimes you expect that the user will only need a single instance of a particular kind of object inside Glish, and you premake it for them so they don't have to. Call these objects defaulttype, for example, defaultlogger, and make then (and the constructor) const to avoid somone inadvertently changing them.

Other considerations

Generally you should not have ``null'' objects. A created object should always be fully manipulatable.

Next: Writing an Application Solely in Glish Up: How to Write an AIPS++ Application Previous: Introduction Contents