howtos:toolcoding:good_practices
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
howtos:toolcoding:good_practices [2010/11/08 16:01] marcus.williams |
howtos:toolcoding:good_practices [2011/06/17 18:42] (current) chris.strashok |
||
|---|---|---|---|
| Line 7: | Line 7: | ||
| - **myObj[t] = create (; dim=SEQ;time:$startYear:$endYear:1;year), where $startYear=1990 and $endYear=2000** | - **myObj[t] = create (; dim=SEQ;time:$startYear:$endYear:1;year), where $startYear=1990 and $endYear=2000** | ||
| - | Method 1 causes problems if you later update the time sequence in the model. If the time sequence changes, all code with hard-coded references the years in that sequence need to be updated in the procedure code, model views, and any TOOL scripts. For larger models, this can be cumbersome and error-prone. | + | Method 1 causes problems if you later update the time sequence in the model. If the time sequence changes, all code that hard-coded references for the years in that sequence need to be updated in the procedure code, model views, and any TOOL scripts. For larger models, this can be cumbersome and error-prone. |
| Method 2 causes problems if you later change the dimensions in myTimeObj. For example, if you add a new dimension so to myTimeObj so that it is now myTimeObj[x,t], myObj in the above code would now be getting its dimension from x, which is now the first dimension, instead of t. This error would most likely be detected during dimensional analysis, but if it somehow were to pass dimensional analysis then the error would be much harder to detect. In either case, the code would have to be updated in the model procedures, model views, and TOOL scripts. | Method 2 causes problems if you later change the dimensions in myTimeObj. For example, if you add a new dimension so to myTimeObj so that it is now myTimeObj[x,t], myObj in the above code would now be getting its dimension from x, which is now the first dimension, instead of t. This error would most likely be detected during dimensional analysis, but if it somehow were to pass dimensional analysis then the error would be much harder to detect. In either case, the code would have to be updated in the model procedures, model views, and TOOL scripts. | ||
| 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 Naming ===== | + | ===== Variable description and name conventions ===== |
| Stub: best practices for variable naming, esp. locals FIXME | Stub: best practices for variable naming, esp. locals FIXME | ||
| - | abbreviations, suffix vs. prefix convention? | + | 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 ^ | ^ Descriptor ^ Abbreviation ^ | ||
| Line 59: | Line 61: | ||
| local population_tot[ts] = sum (population[s,ts,a]; dim1=sex, dim2=age) | local population_tot[ts] = sum (population[s,ts,a]; dim1=sex, dim2=age) | ||
| </code> | </code> | ||
| + | |||
| + | Using underscores can also improve code readability when dealing with raw datasets, especially in calibrator frameworks (e.g. ''CANSIM_Manitoba_imm_1991_2006''). | ||
howtos/toolcoding/good_practices.1289232085.txt.gz · Last modified: 2010/11/08 16:01 by marcus.williams
Page Tools
