Commenting

Most bots require changes after they are placed into production. Use comment to help updates and maintenance.

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:

    Box important sections with equal signs

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

    Use one-line comments to explain assumptions

    Explain known issues and logic insights.

  • Make comments meaningful:

    Example of incorrect commenting

    Correct commenting

  • 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.