Golden Rule 2: Comments and Descriptions

The next golden rule might also be obvious:Always add comments to your work and label your sets, variables, parameters and equations
Now this might be obvious if you have a lot of time, but usually the rule is forgotten if you are stressed and want to finish what you are working on. Not writing comments will probably cost you a lot of time, if you take your model a year from now and see your code: Wow, that looks interesting and very ingenious, but what the %*?!  did I do here? If you send your model to somebody else for help, this person usually don”t want to dechiffer your code. Comments make her life easier too and the chance you get an answer will increase.
In Gams you have many options to add comments:
  • Start a line with a “*” and write your comment, like
* This is a comment
You can change the character “*” in a different character with this command
$comment #
# This is a comment with the new character
  • Put your comment between $ontext and $offtext:
  • Put your comment after some code using  the end-of-line comment possibility after the two characters “!!”
C = IOT(”H”,”CONS”)   !! This is the consumption initialization
Note that this possibility of setting comments is turned off by default. You have to activate it by inserting $oneolcom (on end of line comment)  or $inlinecom (inline comment)
You can also change the default setting of “!!” to two other characters by using $eolcom
Gams-mode for Emacs has a nice feature that allows you to hide multi-line comments (just use Ctrl-c Ctrl-h to hide or show the comments). Hiding the comments gives you a good view on your code
Before hiding:
After hiding:
Writing comments is good practice.
Adding descriptions to your parameters, variables and equations is also good practice. If you use short variable or parameter names, this might save your time, but once again, will make life hard if you look at your model after some time or if your model is big. Was “y” domestic production level or was it income?
If you use descriptions your output is easier to read:
compared with:
Gams-mode for Emacs has another nice feature: if you put your cursor on a parameter or variable in your code and hit F7, another window opens and shows you the description.

Leave a Reply

Your email address will not be published. Required fields are marked *