While most scripts you write will be relatively short and straightforward, it is still a good idea to include comments in your code. Comments are lines of text that are ignored by the computer when the script is run, but they can be very helpful for anyone reading the code (including yourself) to understand what the code is doing.
It is important to write comments that are clear and concise. Comments that tell the reader what the code is doing are not very helpful as they can be inferred from the code itself. Instead, focus on explaining why the code is doing what it is doing, and only explain what the code is doing if it is not immediately obvious. And even then, it's often preferable to rewrite the code to make it more clear rather than adding a comment.
Additionally, comments can be used to separate sections of code such as configuration, input, and output, or to provide context for a specific block of code.
Good comment
# The core switches take ~20s to reply during their nightly config# backup (03:00-03:15). Anything under 25s produced false "host down"# alerts. Do not lower without checking the backup window first.timeout = 30
Concept: Comments
While most scripts you write will be relatively short and straightforward, it is still a good idea to include comments in your code. Comments are lines of text that are ignored by the computer when the script is run, but they can be very helpful for anyone reading the code (including yourself) to understand what the code is doing.
It is important to write comments that are clear and concise. Comments that tell the reader what the code is doing are not very helpful as they can be inferred from the code itself. Instead, focus on explaining why the code is doing what it is doing, and only explain what the code is doing if it is not immediately obvious. And even then, it's often preferable to rewrite the code to make it more clear rather than adding a comment.
Additionally, comments can be used to separate sections of code such as configuration, input, and output, or to provide context for a specific block of code.