Appendix F — Guidelines for Building Applications
General Tips
•
Include reports to files with input data and corresponding output data.
•
Make it intuitive. Provide help, hints, and documentation as necessary.
•
Make it foolproof: “Safe I/O”, “Reset to default data”, and so on.
•
Save a thumbnail image with the model.
•
Include a description text (It will be visible in the COMSOL Server library).
•
Test the application on the computer platforms for which it is intended.
•
Be minimalistic. From the developer’s point of view, it is much easier to make sure logic works, organize, debug, maintain, and further develop the app. From a user’s point of view, it is easier to use the application. The minimalistic approach requires more care while developing but much less maintenance later on and much higher adoption among users.
•
Embed libraries in the model if they are of manageable size.
•
Display the expected computation time and, after the computation, the actual computation time.
•
When a computation is canceled, output data from the previous computation should be cleared.
•
Password protect as needed. (Remember: No one can help you if you forget the password.)
Naming Conventions
In the demo applications in the Application Libraries, all forms, events, declarations, and methods use camelCase. You can adopt this convention also in your own applications. Following this convention, a name should be composed of a number of words joined without spaces, with each word’s initial letter in capitals except the first letter that should be lowercase. Use a descriptive name and long names are better than hard-to-understand short names.
Examples of names for forms:
•
main
•
inputParameters
•
geometryTab
Examples of names for events:
•
updatePlot
•
moveToVelocityTab
Examples of names for declarations:
•
Strings — state, waveguideType
•
Boolean — isError, didChange, hasBeenInitialized
•
Integer — year, nextYear
•
Double — speed, heatTransferCoefficient
Examples of names for methods:
•
compute();
•
computeStudy1();
•
computeStudyAndPlot();
•
getDataForPostProcessing();
•
setPlotType();
Methods
•
Do not create more methods than necessary.
Fewer methods give you a shorter list of methods to browse through when looking for something. Fewer methods usually mean fewer lines of code to worry about.
-
If several methods you wrote do essentially the same thing, consider merging them into one method and dealing with the different cases by input arguments.
-
Do not create a method if it is only called from one place. Insert the code right into that place instead.
•
Create a local method if it is only used in a form, or triggered by a form event or a form object event.
•
Give methods descriptive names and name them so that similar methods are grouped together when sorted alphabetically. You will have less to remember and you will find what you are looking for easier. Long names are better than hard-to-understand short names.
•
The points above apply to method code as well: be minimalistic, use as few lines of code and variables as possible, use descriptive names for variables, use long names instead of hard-to-understand short names, and optimize code to run efficiently.
•
The above points apply to declarations as well: use good names, don't use more than necessary, and declare variables where they are used (in forms and methods or in the model).
Forms
•
Do not create more forms than necessary.
•
Use the Form Wizard templates to get started with creating forms.
•
Consider using subwindows instead of form collections.
•
Give forms descriptive names. Same reasoning as for methods.
•
Make good use of the many different types of form objects. Some are good for some things, while some are good for others.
•
Do not insert more form objects than necessary. Too many options for input data may make the application hard to use. Too much output data makes it hard to find important information.
•
Insert a text field for the user to leave comments to save with the user’s set of input and output data when saving the application.
•
Consider inserting a button with a method to reset to default data.
•
Apply “Safe I/O”:
-
For input fields, alert the user about input data that is out of bounds. You can do that either by an alert triggered by an On Data Change event for an input field, or by setting limits in the form objects settings window, which then sets hard limits. In a method generating the alert, you can just warn the user and then allow the input data if the user chooses to go ahead anyway.
-
On output fields, give the precision that makes sense. If current results are not based on current input data, show it. If the computation failed, show it.
•
Include tooltips, help, documentation, hints, and comprehensive reports.
•
Provide the user with information about how long it takes to run the simulation with default input data on a typical computer. It could be seconds, hours, or even days depending on the application, so that is something the user would like to know before hitting the compute button. Consider playing a sound to alert the user when the computation has finished. The user may be doing something else while waiting for results. (Sending an email message with a report to the user or some other place when the computation is done may be a better alternative if the computation is really long.)
•
Spend some time on the layout of a form. A good-looking form makes it easier and more fun to use the application.
Consider setting keyboard shortcuts for buttons and menu items.