This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
howtos:toolcoding:good_practices [2010/11/05 15:43] deryn.crockett |
howtos:toolcoding:good_practices [2010/11/08 17:03] marcus.williams |
||
---|---|---|---|
Line 24: | Line 24: | ||
Object consolidation is when multiple objects are combined into one along a certain dimension. In this example, we will create an object fuelUseAll[tm], where dimension tm is transportation mode (air, rail, car). Assuming that we have calculated the fuel use for each mode so that we have the objects airFuelUse[], railFuelUse[], and carFuelUse[], we can create fuelUseAll[tm] in two ways: | Object consolidation is when multiple objects are combined into one along a certain dimension. In this example, we will create an object fuelUseAll[tm], where dimension tm is transportation mode (air, rail, car). Assuming that we have calculated the fuel use for each mode so that we have the objects airFuelUse[], railFuelUse[], and carFuelUse[], we can create fuelUseAll[tm] in two ways: | ||
- <code>fuelUseAll[tm] = insert (airFuelUse[]; transMode:air) | - <code>fuelUseAll[tm] = insert (airFuelUse[]; transMode:air) | ||
- | fuelUseAll[tm] = insert (airFuelUse[]; transMode:rail) | + | fuelUseAll[tm] = insert (railFuelUse[]; transMode:rail) |
- | fuelUseAll[tm] = insert (airFuelUse[]; transMode:car)</code> | + | fuelUseAll[tm] = insert (carFuelUse[]; transMode:car)</code> |
- <code>local airFuelUseAll[tm] = copyshape (fuelUseAll[tm]) | - <code>local airFuelUseAll[tm] = copyshape (fuelUseAll[tm]) | ||
local railFuelUseAll[tm] = copyshape (fuelUseAll[tm]) | local railFuelUseAll[tm] = copyshape (fuelUseAll[tm]) | ||
Line 31: | Line 31: | ||
airFuelUseAll[tm] = insert (airFuelUse[]; transMode:air) | airFuelUseAll[tm] = insert (airFuelUse[]; transMode:air) | ||
- | railFuelUseAll[tm] = insert (airFuelUse[]; transMode:rail) | + | railFuelUseAll[tm] = insert (railFuelUse[]; transMode:rail) |
- | carFuelUseAll[tm] = insert (airFuelUse[]; transMode:car) | + | carFuelUseAll[tm] = insert (carFuelUse[]; transMode:car) |
fuelUseAll[tm] = airFuelUseAll[tm] + railFuelUseAll[tm] + carFuelUseAll[tm] | fuelUseAll[tm] = airFuelUseAll[tm] + railFuelUseAll[tm] + carFuelUseAll[tm] | ||
Line 39: | Line 39: | ||
Method 2 is the recommended method for consolidating objects. The main advantage is that with method 2 if airFuelUse[], railFuelUse[], or carFuelUse[] were empty objects, this would be detected when trying to view fuelUseAll[tm]. With method 1, an empty object would not necessarily be detected when viewing fuelUseAll[tm]. If railFuelUse[] were empty, the values for rail in fuelUseAll would just become 0 after carFuelUse[] is inserted so the empty object would go undetected. | Method 2 is the recommended method for consolidating objects. The main advantage is that with method 2 if airFuelUse[], railFuelUse[], or carFuelUse[] were empty objects, this would be detected when trying to view fuelUseAll[tm]. With method 1, an empty object would not necessarily be detected when viewing fuelUseAll[tm]. If railFuelUse[] were empty, the values for rail in fuelUseAll would just become 0 after carFuelUse[] is inserted so the empty object would go undetected. | ||
+ | ===== Variable description and name conventions ===== | ||
+ | |||
+ | Stub: best practices for variable naming, esp. locals FIXME | ||
+ | |||
+ | It is generally recommended that variable names use the [[http://en.wikipedia.org/wiki/CamelCase|lowerCamelCase]] convention. However, in some cases the use of underscores in conjunction with lowerCamelCase for coding clarity is appropriate (especially for procedures, views and source datasets). | ||
+ | |||
+ | Variable description modifiers should be used as suffixes, rather than prefixes (e.g. //dwelling unit share// rather than //share of dwelling units//). The same is true for variable names, but for these modifier abbreviations are recommended to keep name lengths manageable (e.g. ''dwellUnitShr''). A table of suggested abbreviations is provided below: | ||
+ | |||
+ | ^ Descriptor ^ Abbreviation ^ | ||
+ | | share | Shr | | ||
+ | | intensity | Int | | ||
+ | | rate | Rt | | ||
+ | | efficiency | Eff | | ||
+ | | plan | Plan | | ||
+ | | actual | Act | | ||
+ | |||
+ | |||
+ | Local variables in a procedure or view can proliferate as a result of reorder(), sum(), etc. operations. For code readability it is recommended that local variables created from a modelbase variables be named using the modelbase variable name followed by underscore and a meaningful descriptor. For example: | ||
+ | |||
+ | <code> | ||
+ | local population_tot[ts] = sum (population[s,ts,a]; dim1=sex, dim2=age) | ||
+ | </code> | ||
+ | |||
+ | Using underscores can also improve code readability when dealing with raw datasets, especially in calibrator frameworks (e.g. ''CANSIM_Manitoba_imm_1991_2006''). | ||