conventions to be used in modgen models by claude charette [email protected] workshop for...

Conventions to be used in Conventions to be used in Modgen modelsModgen models

bybyClaude CharetteClaude Charette

[email protected]@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


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();();

}}}}


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

};};


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

};};


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();();

}}}}


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


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


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


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;}}


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;} }


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

conventions to be used in modgen models by claude charette [email protected] workshop for...

Documents