Most bots require changes after they are placed into production. Sometimes those changes can be frequent, depending on the type and scope of the bot. The difference between a change being a relatively straight-forward task and a complete nightmare is determined by two things: how clean is the bot architecture, and how well the bot is documented and commented.

Good commenting can mean a difference of hours during a maintenance cycle. Write all comments in the same language, ensure they are grammatically correct and contain appropriate punctuation.

General Commenting Rules

• Box important sections with repeating slashes, asterisks, or equal signs:

  

• Use one-line comments to explain assumptions, known issues and logic insights, or mark automation segments:

  

  

• Make comments meaningful:

  

  

• Always use comments when you identify bad task lines with some common phrase, such as //FIX THIS – otherwise remove or rewrite that part of the task!
• Include comments using Task-List keyword flags to allow comment-filtering. Example:

  // TODO: Place database command here

  // UNDONE: Removed keystroke command due to errors
                              here

• Never leave disabled task lines in the final production version. Always delete disabled task lines.
• Try to focus comments on the why and what of a command block and not the how. Try to help the reader understand why you chose a certain solution or approach and what you are trying to achieve. If applicable, also mention that you chose an alternative solution because you ran into a problem with the obvious solution.