[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

SparForte Best Practices

There are many theories for script layout, variable naming and so forth. I don't recommend or endorse any paritcular "best practices" standards. However, if you are looking for suggestions to base coding standards on, here are some ideas:

  • If script file names are simple, with letters, numbers and underscores, they are easily ported to different operating systems

  • Consider using a standard layout for the start of all scripts, with comments for who created the script and any source control elements.

  • Use pragma annotate instead of comments to describe how to use a script. The help command can shows these annotations. Describe the usage: leave notes on the history, implementation or design as comments. Annotate can then serve the same function as an Ada package specification.

  • Use pragma ada_95 in scripts where you want to copy your routines to Ada programs.

  • Variable naming in the standard Ada packages usually use words with beginning with upper-case and containing an underscore (e.g. Put_Line). Shell conventions use upper-case for variable names. Since SparForte is case-sensitive, SparForte uses lower-case words with underscores to fit to the conventions of UNIX shell-scripting.

  • Sticking to lower-case will make it easier to reuse code with Ada and SparForte

  • Avoid using names that vary only in case. (e.g. do not use "x" and "X".)

  • Ada conventions use full words in functions or variable names whereever possible. (e.g. unbiased_rounding() .) Avoid acronyms, especially when they can be ambiguous, unless the acronym is a common one.

  • Don't use universal variable types in scripts.

  • For unfinished sections, consider using put_line("not yet written") instead of a simple null.

  • Use comments on a separate line to identify sections of a script, or to explain design decisions, potential problems or workarounds

  • Don't rely on separator characters such as lines of "=" or "*" to make comments stand out. Instead, use blank lines and whitespace.

  • Use a usage functions and show the usage when "-h" or "--help" are used to run the script

  • Put complicated routines into a function, procedore or a declare block. Declare any local variables in the local scope to improve readability and reduce the scope and clutter of variables.

  • Declare one item per line.

  • Use one mathematical operation per line. Break up long expressions and use temporary variables. This makes debugging the partial results easier.

  • Use pragma assert and pragma debug during development. These only run when --debug is used.

  • Use the source_info package to display location information in messages.

  • Apply consistent spacing and indentation throughout a script.

 
[Right Submenu]

 Command Prompt Tutorial 1: SparForte as a Calculator

 Command Prompt Tutorial 2: Basic Shell Commands

 Command Prompt Tutorial 3: Working with Databases

 Script Tutorial 1: Basic Commands Scripts

 Script Tutorial 2: Intermediate Program Scripts

 Script Tutorial 3: Data Types

 Template Tutorial 1: Basic Templates

 Template Tutorial 2: Intermediate Templates

 GCC Tutorial: Compiling SparForte Scripts

 Debugging Tutorial - Using the SparForte Debugger

 Creating a Profile Script

 Calling SparForte from C: A Tutorial

 SparForte For PHP Developers

 SparForte Best Practices

[Back to Top] Back To Top [Small Forte Symbol]