This question is more about English.
When writing scripts, I often need to point out things that can be changed if the user wants or needs to change them.
For example, if the user simply doesn’t like Helvetica font, then he or she can change it to e.g. Times, or if the system is slow, the user needs to change the delay from 1 second to e.g. 2.
Currently, for these things, I use comments “Edit as desired” and “Edit as necessary”. But are they really grammatical enough? Maybe there are better alternatives?
English is not my native language, and in my country we don’t speak it. But I would prefer my comments to not look like barbarian inscriptions.
delay 1 -- edit as necessary
Historically, if someone was doing any kind of programming, the assumption was made that even if they were not a professional, they would at least know a little bit about what they were doing. These days that is not necessarily the case, so you may need to ask yourself if your audience has the skill or is even going to know what you are talking about. This is where memes like “press any key” came from.
As you mentioned, many scripts can be (or need to be) customized for the user’s environment, and it is typical to make these comments. Other options would be to use properties for some of the more common customizations (which could be grouped together with comments of their own), or include examples or complete commented statements with (safe) variations. A larger comment block detailing a particular setting or even what the handler/code section is doing could also be used (I use them for larger projects), but it makes a lot of sense to locate comments where things can be edited as necessary.
There are those that like compact code, single letter variables, and no comments, while others will fill the screen for something trivial. And some are just weird (you know who you are). Like writing the script itself, it mostly comes down to your personal preference. Unless you are targeting a particular audience, comments would mostly be to help a future you figure out what the current you was thinking.
1 Like
I don’t know how much value I’m adding here, red_menace has hit all the high points.
--This comment provides no additional information.
delay 1 -- edit as necessary
--This comment explains why the delay command is included.
delay 1 --for UI to load
--This comment is grammatically correct about it.
delay 1 --This application requires time to load the UI
--This comment explains why the delay is included and why it may need to be edited by the user.
delay 1 --This application requires time to load the UI. Slower systems may require more delay.
--Variables can self-comment. But this seems silly.
set UI_load_time_delay to 1
delay UI_load_time_delay
--However, If the delay is used repeatedly then Properties can self-comment and make it easier to make the change consistently.
property UI_load_time_delay : 1
delay UI_load_time_delay
1 Like