In NetLogo 2.x it doesn't matter, but in NetLogo 1.x the name of the model file, including the ".nlogo" suffix, must be 31 or fewer characters (since this is the longest filename possible on MacOS 8 and 9). Most models will not be backported to NetLogo 1.x so usually this isn't a concern.
Name closely related models so they alphabetize together, even if makes the names read oddly. So for example: GasLab Gas in a Box, GasLab Free Gas, CA 1D Elementary, CA 1D Totalistic, etc.
Correct: My Amazing Model.nlogo
Incorrect: my amazing model.nlogo, My amazing model.nlogo, MyAmazingModel.nlogo
If a StarLogoT version exists, run the StarLogoT version and make sure the NetLogo one behaves in a similar way. Does the model exhibit all of the behaviors it is supposed to exhibit?
Are there other implementations of the same or similar rules out there on the web? It might be worth checking this model against those, too.
Does the "go" button unpress itself if the model reaches a natural stopping point (example: all the turtles are dead)? If not, use the stop primitive so this happens.
If the "go" button uses stop to stop itself, the stopping check should be at the top of the go procedure, not the bottom. This is wrong:
to go ask turtles [ ... ] if not any? turtles [ stop ] end
Do this instead:
to go if not any? turtles [ stop ] ask turtles [ ... ] end
That way even if the user tries to press "go" again, nothing will happen. They shouldn't be able to force the model to step forward by repeatedly pressing "go" (especially since in some models that might cause bad behavior, such as a runtime error).
Not all models have natural stopping conditions (such as all the turtles being dead) -- many models just run forever and therefore have no need for added code like this.
If the model uses turtle shapes, does it still look good if you turn shapes off? (Sometimes modelers use shapes with fixed colors and then don't bother to set the color of the turtles, which means if you turn shapes off suddenly you have rainbow-colored turtles.) Note that shapes are automatically off if the patch size is reduced to 2 or less.
Some models have setup procedures that take values from several sliders. In the past, modelers have written procedures that cause run-time errors for certain combinations of the slider values. The modelers missed these combinations, because there were so many possible combinations. If you are concerned that the model you are checking could have such a problem, one way to go about it is to run the model through BehaviorSpace, making sure that all the slider combinations are covered.
Remove any "speed" or "slowdown" slider that only uses every or wait to slow the model down, since NetLogo's control strip has a built-in speed slider for every model.
Use the "units" slot in sliders if appropriate to indicate what units the slider is in.
Some sliders should be integer sliders, others floating point sliders. For example, a num-turtles slider should return integers, but a infection-chance slider would be floating point. It depends on whether the quantity is conceptually an integer, or whether it could theoretically vary continuously. Even if the actual increment of the slider is 1.0 or a multiple of 1.0, if the quantity is conceptually continuous, the slider should be floating point. (You can turn a floating point slider into an integer slider by removing the ".0" from the min, max, increment, and current value.)
Name sliders and switches like this: leopard-spot-count, and not like leopardspotcount or leopardSpotCount or leopard_spot_count
Switches should have names ending in question marks, like this: grow-grass?
Don't make widgets just-barely-wide-enough to display the text on them; leave a little extra width, to allow for the different fonts on different operating systems. (You don't need to leave extra space between widgets, only inside widgets.) (If you want to really sure the text fits, the VM with the largest font seems to be on Macs, so you may want to test your model on that.)
Set the number of decimal places in monitors appropriately. (The default is 3, but in many cases 1 or 2 would be more appropriate.)
Decide if shapes should be used; if not, turn them off for speed. If so, then make sure appropriate shapes are used (perhaps draw some in the shapes editor).
All shapes need names. There's no need to end shape names in "-shape", like "circle-shape"; just say "circle".
Put the 2D view on the bottom right, so it can easily be made larger without covering other widgets. It's best not to put anything to the right or below the view (although for some models with very crowded interfaces sometimes we throw up our hands and do it anyway).
When deciding on the overall window size, it's best if everything can fit on a 800x600 display. If that isn't possible, it should really fit on an 1024x768 display, but remember to leave some room for taskbar, dock, menubar, etc. If fitting comfortably within 1024x768 is impossible, then you should consider what will happen when the interface tab becomes scrollable and position widgets appropriately.
If the model doesn't use the view, it's OK to make the view very short by setting screen-edge-y to 0, but don't try to make it super narrow by setting screen-edge-x to something tiny. It's better to let the 2D view have a normal width so the speed slider is the normal size and all of the controls in the control strip are visible.
Make the patch size a round number (e.g. 10.0 not 10.7). This usually makes the 2D view look a little nicer.
If the model is for NetLogo 2.x, think about whether each forever button should have the "Force display update after each run" checkbox checked. Checking makes the model run slower, but gives smoother screen updates. For some models the smoothness isn't really worth it, for example Fire. For other models it's more important that every step of the model is made visible to the user before moving on to the next step. Pay attention also to auxiliary forever buttons that aren't go buttons, but perform other functions like letting you interact with the view using the mouse -- most such buttons should have this checkbox turned off.
If the model needs to tell the user that something has gone wrong, use user-message. If you use show or print, the user might not see it because they might have hidden the command center.
If the model wants to print messages from time to time as it runs, it should use print. If you do this, consider adding an Output area to the interface. Doing so has several advantages:
If you use an output area, consider adding a call to clear-output to the model's setup procedure. This might or might not be appropriate depending on whether you think the user might want to refer back to output from previous runs. When in doubt, don't include it.
We can now assign keyboard equivalents to buttons in the Interface tab, so that (for example) pressing "G" will be the same as clicking on the "Go" button. However, you should refrain from assigning such action keys unless the model will significantly benefit. Games are a good example of where action keys can be particularly useful.
Think about whether view wrapping should be on or off. Regardless of whether anything actually wraps determine if the world modelled is logically a torus, a box, or something else.
The first paragraph only of WHAT IS IT? is what will show up in the Models Library dialog when the model is selected. So the first paragraph should be able so stand on its own as a brief and self-contained description of the model.
It isn't called that, it's called the view. Usually it's not necessary to specify 2D view or 3D view, but in some contexts specifying may be appropriate.
Check the Procedures tab for this as well -- a comment there might refer to the graphics window.
Make sure the text (except for the "NetLogo Features" section) does not assume familiarity with NetLogo programming. For example, it shouldn't refer to "turtles" when it could just say rabbits or molecules or people or what have you. Similarly for "patches", "observer", and other NetLogo jargon. (This isn't a necessarily a hard-and-fast, 100%-of-the-time rule... use your judgment.)
Don't put the model name at the top.
Only printable ASCII characters (letters, numbers, and basic typewriter-like symbols) should be in a model, but the Info tab is where you're most likely to see a violation of this rule. Non-ASCII characters, such as those with European accents, should be removed. This might seem like an easy rule to follow, but Microsoft Word automatically uses "smart" quotation marks, apostrophes, and hyphens that are angled differently at the beginning and end of a word. Pasting from MS Word into NetLogo can introduce these illegal characters. The only legal quotation marks in a NetLogo model are ' and ", and the only legal hyphens consist of one or more - characters.
Remove manual line breaks from info tabs. NetLogo will do its own line-wrapping based on the width of the window (unlike StarLogoT and earlier NetLogos).
In NetLogo, the info tab is in a fixed width font, but when the text appears in the Models Library on the NetLogo web site, it will be in a non fixed width font. If there are any parts of the info tab that must be in a fixed width font to line up correctly, then put a "|" character at the beginning of each such line. Example:
| 1% + - | H-A + H O <========> H O + A | 2 3
Proofread the info text for spelling and grammar. (At a minimum, you should paste the text into a word processor and use its spell check feature.)
Make sure the default slider settings are sensible (and match what is described in the info tab, if slider settings are discussed there).
Be careful -- it's easy to accidentally change slider settings when you are fooling with the model. Don't inadvertently save changes you didn't want saved.
Use two spaces after a period, not just one, to enhance readability.
Remove any extra blank lines from the end.
As of NetLogo 2.1, it's called a "chooser". (Before it was a "choice".) Some old models may still use the old name; this should be fixed.
Be sure that each of the following sections are found in the Info Tab with the following formatting. There should be two blank lines between sections. There should be no section headers other than these. ( no other lines that have all capital letters and no lowercase. ) In the past it has been the practice to have subheadings in all capital letters, however, these should be changed to have lowercase letters.
WHAT IS IT?
-----------
This section should give a general understanding of what the model is trying to explain or show.
HOW IT WORKS
------------
This section should explain what rules the agents use to create the overall behavior of the model.
HOW TO USE IT
-------------
This section should explain how to use the model, including a description of each of the widgets in the Interface Tab.
THINGS TO NOTICE
----------------
This section should give some ideas of things for the user to notice while running the model.
THINGS TO TRY
-------------
This section should give some ideas of things for the user to try to do (move sliders, switches, etc.) with the model.
EXTENDING THE MODEL
-------------------
This section should give some ideas of things to write in the Procedures Tab to make the model more complicated, detailed, accurate to life, etc.
NETLOGO FEATURES
----------------
This section should point out any especially interesting or unusual features of NetLogo that the model makes use of, particularly in the Procedures tab. It might also point out places where workarounds were needed because of missing features.
RELATED MODELS
--------------
This section should give the names of related models in the Models Library.
CREDITS AND REFERENCES
----------------------
This section should contain the reference found below as well as any other necessary credits or references.
If the model is based on published sources (or web sites), it's good to include reference (or URL) information here.
NetLogo models (and HubNet activities) are dual purpose. They are vehicles for content, but every model is also a code example. Ideally, all of the code in every model in the Models Library should be technically, stylistically, and visually exemplary, because looking at our models is one of the main ways that NetLogo users learn how to code and learn what good code looks like.
Below are a lot of specific do's and don't's for NetLogo code, but it's not an exhaustive list. When you're checking out a model, please do your best to make sure that the code (including comments) is the best possible code that you can make it.
Make sure code is adequately commented. Don't assume that users are expert programmers. It's particularly important to comment anything unusual, tricky, or obscure in the code -- much less important to comment every variable or every line of code.
If it says that at the top, get rid of it.
StarLogoT forces slider and switch names to be very short; NetLogo doesn't have that restriction, so if you're converting an old StarLogoT model, consider using longer, less cryptic names
Every Boolean (true/false) variable and reporter (and switch) should have a name ending in a question mark, like this: grow-grass?
Put the procedures in a logical order: setup, then go, then supporting procedures, then plotting procedures at the end (since these are often the least interesting)
Any turtle or patch procedure should be commented as follows:
to go ask turtles [move] end to move ;; turtle procedure fd 1 end
Breed names should be plural: e.g. wolves, not wolf (exception: when only one of that breed is ever created)
Be turtle-centric! Never use set heading unless you have to:
Name variables like this: leopard-spot-count, and not like leopardspotcount or leopardSpotCount or leopard_spot_count
The code should be as easy to read as possible. Look at other models to see what easy to read code looks like. We haven't really arrived at a uniform style for where to put line breaks and spaces, etc., but whatever style you choose, apply it consistently.
Remove tab characters from code; indent in multiples of two spaces instead. (Finding tab characters is easier if you do it in a word processor or text editor such as Word, Emacs, etc.)
Remove any extra blank lines from the end.
using the model shouldn't require that the command center be visible; it should always be OK for the user to hide it
instead, either use USER-MESSAGE, or add an output area to the interface and use OUTPUT-SHOW/TYPE/PRINT
Instead of this:
sprout 1 [ set breed wolves ... ] hatch 1 [ set breed wolves ... ]
Write this instead:
sprout-wolves 1 [ ... ] hatch-wolves 1 [ ... ]
(as of NetLogo 2.1beta2)
Models built for NetLogo 2.1 or later should always use let, never locals. Search for occurrences of "locals" and change them.
make sure that random-int-or-float is never used; use random or random-float instead depending on whether you want an integer answer or a floating point answer.
Don't use random when random-float would more appropriate, or vice versa; don't restrict the result to be an integer unless that really makes sense. For example say rt random-float 360 instead of rt random 360 because there's no reason to restrict the turtle to only integer headings.
if the display and no-display commands are used, be sure they are really needed; there are some models that needed them in 1.x in order to run fast, but are fast in 2.x even without them
Make sure to startup is only used if really necessary.
Use patch-ahead instead of dx and dy if possible; also look for opportunities to use patch-left/right-and-ahead instead of more complicated means of accomplishing the same thing
Use cct or create-custom-BREED if possible & appropriate (instead of crt/create-BREED)
Don't use the cct-BREED abbreviation; spell it out create-custom-BREED; but it's OK to use cct by itself
Use set-default-shape instead of set shape if possible.
Use the self and myself reporters to avoid use of turtle "who" numbers when possible. Examples:
Replace uses of the nsum and nsum4 primitives with the new, more flexible neighbors and neighbors4 primitives
Replace all uses of output with report -- output is an old alias we're no longer using.
Replace all uses of pc with pcolor -- pc is an old alias we're no longer using.
Replace all uses of temporary plot pens (plot pens created by create-temporary-plot-pen) with permanent plot pens (plot pens that are defined in the plot edit dialog) unless you are certain they are necessary (in 99% of models, they are not). Usually this is only a problem with really old models (such as models converted from StarLogoT).
Remove any setup-plot procedure from the Procedures tab and instead set the appropriate values in the plot edit dialog, unless you are sure the setup-plot procedure is necessary (in 90%+ of models, it is not). You would need a setup-plot procedure if, for example, you want to set the x or y range to some dynamic value (such as the number of turtles).
The following bug is common, in fact nearly ubiquitous, in StarLogoT and NetLogo models. Please check for it. Many models use the following pattern to do plotting:
to setup ... setup-plots end
to go ... do-plots end
The bug is that the initial state of the system is never plotted! What should be the first point in your plots, never gets drawn. Check for this bug, and if you see it, fix it by adding a call to do-plots at the end of setup.