Nasal Best Practices

FlightGear coding in Nasal is easy, but there are some best practices to consider to make your code easier to read and neater.

These are merely opinions; you may use any format you wish. However, it would be great if users could use this format, to make formatting more consistent across FlightGear.

Comments

Comments should use the following format:

#######################################
# Use this to split up blocks of code #
########################################
var xyz = 1
var abc = 2 # Note that there is a space after the hash

Comments should be used primarily to describe WHY code does what it does and WHAT it is doing. Usually there is no need to say HOW it is doing it, as that should be self-evident, unless your code is too complex! For instance, we could have the following:

# Checks whether we should create ice
# Icing conditions: freezing fog or low temp and below dp or in advanced wx cloud

var spread = temperature - dewpoint; 
if ((spread < maxSpread and temperature < 0) or (temperature < 0 and visibility < 1000) or (visibLclWx < 5000 and temperature < 0)) { 
# we use two visibility properties: one is for basic wx and the other is for advanced wx 		
   setprop("/systems/icing/icingcond", 1);
} else {
   setprop("/systems/icing/icingcond", 0);
}

Spaces vs Tabs

This has divided many developers! I feel the best method is to use tabs at the start of a line and to use spaces within a line. For example:

# we use spaces within the line to make it easier to read
if ((spread < maxSpread and temperature < 0) or (temperature < 0 and visibility < 1000) or (visibLclWx < 5000 and temperature < 0)) { 
# we tabs to move the "true" and "false" statement to the second column	
   setprop("/systems/icing/icingcond", 1);
} else {
   setprop("/systems/icing/icingcond", 0);
}

Another example:

var abc = 1;
var def = getprop("/abc/def/ghi");
# Note that there is a space around the '='!

Whichever method you choose, be consistent throughout your coding!

Lining up code

This applies to both Nasal and XML. I will use XML in this example. Use spaces to line up code within a code block; that is:

<filter>
	<name>VS-target-cmd</name>
	<type>gain</type>
	<gain>1</gain>
	<update-interval-secs type="double">0.05</update-interval-secs>
	<input>
		<expression>
			<table>
				<property>/it-autoflight/internal/vert-speed-fpm</property> 
				<entry><ind>-50000</ind><dep> -750</dep></entry>
				<entry><ind> -2000</ind><dep> -750</dep></entry>
				<entry><ind> -1000</ind><dep> -250</dep></entry>
				<entry><ind>     0</ind><dep>    0</dep></entry>
				<entry><ind>  1000</ind><dep>  810</dep></entry>
				<entry><ind>  2000</ind><dep> 1640</dep></entry>
				<entry><ind>  3000</ind><dep> 2100</dep></entry>
				<entry><ind>  4000</ind><dep> 2440</dep></entry>
				<entry><ind>  5000</ind><dep> 3000</dep></entry>
				<entry><ind> 10000</ind><dep> 5000</dep></entry>
				<entry><ind> 50000</ind><dep>50000</dep></entry>
			</table>
		</expression>
	</input>
	<output>/systems/pressurization/targetvs-cmd</output>
</filter>

Look particularly at the <table> part. Note how the last line lines up. This makes the code easy to read.