Post on 15-Jan-2016
description
transcript
Conventions to be used in Conventions to be used in Modgen modelsModgen models
bybyClaude CharetteClaude Charette
Claude.Charette@statcan.caClaude.Charette@statcan.ca
Workshop for Modgen usersWorkshop for Modgen usersMay 27th, 2008May 27th, 2008
www.statcan.ca/english/spsd/Modgen.htmwww.statcan.ca/english/spsd/Modgen.htm
Goals of usage of conventionsGoals of usage of conventions
Better understanding of codeBetter understanding of code
Team workTeam work
Cooperation between different teamsCooperation between different teams
Bugs waiting to happenBugs waiting to happen
Categories of conventionsCategories of conventions
Names of Modgen symbolsNames of Modgen symbols
Names of variablesNames of variables
Code layoutCode layout
Other layout conventions specific to Other layout conventions specific to ModgenModgen
Bugs waiting to happenBugs waiting to happen
Names of Modgen symbolsNames of Modgen symbols
Principles to follow when choosing Principles to follow when choosing conventions:conventions:– Must help avoid collisions between names of Must help avoid collisions between names of
different symbolsdifferent symbols– Must help in recognizing kind of symbolMust help in recognizing kind of symbol– Must not pollute the model’s interfaceMust not pollute the model’s interface
Modgen symbols
Actors Actor sets
States Events
Functions Groups
Links
TablesParameters
Modules
Types Classification values
Symbol categoriesSymbol categories
Symbol category Conventions Examples
ActorsTables
-Capital letter at the start of each word-Underline between each word
Student_Weekly_Earning_Rate
Actor setsEventsFunctionsLinksModulesParameters
-Capital letter at the start of each word-No spaces between words
PersonCore
-Single links -Prefix “l” link Person.lSpouselink RPP_Plan.lOwner Person.mlPlans[]
-Multiple links -Prefix “ml” link Person.mlBiologicalChildren[]link RPP_Plan.lOwner Person.mlPlans[]
-Actor sets -Prefix “as” actor_set Person asPersons;
- Event – time functions -Prefix “time”-Suffix “Event”
timeClockEvent
- Events – functions -Suffix “Event” ClockEvent
Symbol category(…end)
Conventions(…end)
Examples(…end)
States -Small letters only-Underline between each word
minorite_visible
GroupsTypes
-Capital letters only-Underline between each word
MINORITE_VISIBLE
- Classification values -Prefix for the classification name: first letter of each word in the classification name followed by any number in the classification name
Values de la classification MINORITE_VISIBLE2:MV2_VISIBLEMV2_NON_VISIBLE
Names of variablesNames of variables
Local variables, global variables, function Local variables, global variables, function argumentsarguments
Type Prefix Example
bool b bool bReturn = {false};
CString sz CString szBuf = “” ;
double d double dTemps = {0.0};
float f float fTemps = {0.0};
int n int nAnneeIndex = {0};
TIME t TIME tDebug = {TIME_INFINITE};
Type created in the model:-Classifications-Ranges-Partitions
Comprised of the first letter of each word in the type’s name, in small letters
EDUCATION_STATUS esPreviousStatus = {ES_PRE_SCHOOL};
Code layoutCode layout
Only one instruction per lineOnly one instruction per line
IndentationIndentation
Using curly bracketsUsing curly brackets
Meaningful namesMeaningful names
Code layout (continued)Code layout (continued)
Only one instruction per lineOnly one instruction per lineBad example:Bad example:
voidvoid SimulationSimulation(){(){ intint nCase; nCase; forfor ( nCase ( nCase == 0; nCase 0; nCase << CASESCASES() () &&&& !!gbInterrupted gbInterrupted
&&&& !!gbCancelled gbCancelled &&&& !!gbErrors;nCasegbErrors;nCase++++ ){ ){ StartCaseStartCase(); (); CaseSimulationCaseSimulation(); (); SignalCaseSignalCase();(); } }}}
GoodGood example: example:
voidvoid SimulationSimulation(){(){intint nCase; nCase;forfor ( nCase ( nCase == 0; nCase 0; nCase << CASESCASES() () &&&& !!gbInterrupted gbInterrupted
&&&& !!gbCancelled gbCancelled &&&& !!gbErrors;nCasegbErrors;nCase++++ ){ ){StartCaseStartCase(); (); CaseSimulationCaseSimulation(); (); SignalCaseSignalCase();();
}}}}
Code layout (continued)Code layout (continued)
IndentationIndentation– Blocs left alignedBlocs left aligned– Subblocks shifted to the rigthSubblocks shifted to the rigth
Bad example:Bad example:
classificationclassification LANGUE2 { LANGUE2 {//EN francophone//EN francophoneL2_FRANCO,L2_FRANCO,//EN non francophone//EN non francophoneL2_NON_FRANCOL2_NON_FRANCO};};
GoodGood exemple: exemple:
classification classification LANGUE2 {LANGUE2 {//EN francophone//EN francophoneL2_FRANCO,L2_FRANCO,//EN non francophone//EN non francophoneL2_NON_FRANCOL2_NON_FRANCO
};};
Code layout (continued)Code layout (continued)
Using curly bracketsUsing curly brackets– Opening bracket on separate lineOpening bracket on separate line– Brackets left-aligned with parent blockBrackets left-aligned with parent block
Bad example:Bad example:
classificationclassification LANGUE2 { LANGUE2 {//EN francophone//EN francophoneL2_FRANCO,L2_FRANCO,//EN non francophone//EN non francophoneL2_NON_FRANCOL2_NON_FRANCO
};};
GoodGood exemple: exemple:
classification classification LANGUE2LANGUE2{{
//EN francophone//EN francophoneL2_FRANCO,L2_FRANCO,//EN non francophone//EN non francophoneL2_NON_FRANCOL2_NON_FRANCO
};};
Code layout (continued)Code layout (continued)
Using curly bracketsUsing curly bracketsBad example:Bad example:
voidvoid SimulationSimulation(){(){intint nCase; nCase;forfor ( nCase ( nCase == 0; nCase 0; nCase << CASESCASES() () &&&& !!gbInterrupted gbInterrupted &&&&
!!gbCancelled gbCancelled &&&& !!gbErrors;nCasegbErrors;nCase++++ ){ ){StartCaseStartCase(); (); CaseSimulationCaseSimulation(); (); SignalCaseSignalCase();();
}}}}
Good example:Good example:voidvoid SimulationSimulation()(){{
intint nCase; nCase;forfor ( nCase ( nCase == 0; nCase 0; nCase << CASESCASES() () &&&& !!gbInterrupted gbInterrupted &&&&
!!gbCancelled gbCancelled &&&& !!gbErrors;nCasegbErrors;nCase++++ ) ){{StartCaseStartCase(); (); CaseSimulationCaseSimulation(); (); SignalCaseSignalCase();();
}}}}
Code layout (continued)Code layout (continued)
Meaningful namesMeaningful namesBad examples:Bad examples:
Variables: Variables: int nJ;int nJ;Symbols:Symbols: classificationclassification TYPE2 TYPE2
{{UL_VS_MARIE,UL_VS_MARIE,
HU_VS_MARIEHU_VS_MARIE};};
Layout conventions specific to Layout conventions specific to ModgenModgen
AbbreviationsAbbreviations
Choosing a single working languageChoosing a single working language
Two-letter language codesTwo-letter language codes
Initializing variables and states using curly Initializing variables and states using curly bracketsbrackets
Meaningful numberingMeaningful numbering
Layout conventions specific to Layout conventions specific to Modgen (continued)Modgen (continued)
AbbreviationsAbbreviations– Hard to understand for the non-initiatedHard to understand for the non-initiated– To be avoided as much as possibleTo be avoided as much as possible– Documentation mandatoryDocumentation mandatory
Example:Example:
ULHUULHU
Layout conventions specific to Layout conventions specific to Modgen (continued)Modgen (continued)
Choosing a single working languageChoosing a single working language– Easier to translateEasier to translate– Used also for abbreviationsUsed also for abbreviations
ExampleExample: vismin: vismin
Two-letter language codesTwo-letter language codes– Industry standardIndustry standard– EN for EnglishEN for English– FR for FrenchFR for French
Meaningful numberingMeaningful numbering
Bugs waiting to happenBugs waiting to happen
Initializing all variablesInitializing all variables
Avoiding global variablesAvoiding global variables
Using curly brackets in conditional blocksUsing curly brackets in conditional blocks
Using constantsUsing constants
Using variables for temporary state values Using variables for temporary state values in eventsin events
Bugs waiting to happen (continued)Bugs waiting to happen (continued)
Initializing all variablesInitializing all variables– Value of a non-initialized variable depends on Value of a non-initialized variable depends on
memory state of the systemmemory state of the system– Can cause bugs that are not reproducible Can cause bugs that are not reproducible – Always initialize using curly bracketsAlways initialize using curly brackets– Not necessary to initialize symbolsNot necessary to initialize symbols
Bugs waiting to happen (continued)Bugs waiting to happen (continued)
Using global variablesUsing global variables– Should be avoidedShould be avoided– Will cause problem if more than one Will cause problem if more than one
simulation threadsimulation thread– Using model-generated parameters is Using model-generated parameters is
preferedprefered
Bugs waiting to happen (continued)Bugs waiting to happen (continued)
Using curly brackets in conditional blocksUsing curly brackets in conditional blocks– Prevents errors when code addedPrevents errors when code added
Bad example:Bad example:ifif (dAleatoireAnniversaire (dAleatoireAnniversaire <=<= dProbul) dProbul)
etat_mat etat_mat == EM_UNION_LIBRE; EM_UNION_LIBRE;elseelse etat_mat etat_mat == EM_MARIE; EM_MARIE;
Good example:Good example:
ifif (dAleatoireAnniversaire (dAleatoireAnniversaire <=<= dProbul) dProbul) {{
etat_mat etat_mat == EM_UNION_LIBRE; EM_UNION_LIBRE;}}elseelse {{
etat_mat etat_mat == EM_MARIE; EM_MARIE;}}
Bugs waiting to happen (continued)Bugs waiting to happen (continued)
Using constantsUsing constants– Mostly used for:Mostly used for:
Initializing variables or statesInitializing variables or statesComparisonsComparisonsExample:Example:ifif (nAge (nAge !=!= 111) 111) {{
nAge nAge == nAge nAge + + 1;1;}}
– Other options:Other options:Declared constantsDeclared constantsExample:Example:constconst intint nAgeMax nAgeMax == {111}; {111};MIN and MAX macrosMIN and MAX macrosExample:Example:ifif (nAge (nAge !=!= MAXMAX(AGE_MORTALITE)) (AGE_MORTALITE)) {{
nAge nAge == nAge nAge + + 1;1;} }
Bugs waiting to happen (continued)Bugs waiting to happen (continued)
Temporary state values in eventsTemporary state values in events– Weird results in BioBrowserWeird results in BioBrowser– Using a local variable is preferredUsing a local variable is preferred