コメント作成

ほとんどの Bot は、本番環境に配置した後で変更が必要になります。コメントを使用すると、更新やメンテナンスの際に役立ちます。

ほとんどの Bot は、本番環境に配置した後で変更が必要になります。Bot の種類や範囲によっては、このような変更が頻繁に発生する場合があります。変更が比較的容易または極めて複雑なタスクになるのかは、Bot アーキテクチャの鮮明度と、Bot がどれくらいよく文書化され、コメントが付いているのかによって異なります。

適切なコメントを追加することによって、メンテナンス サイクルの時間を大幅に節約することができます。コメントはすべて同じ言語で記述し、文法的に正しく、句読点が適切に使われていることを確認しましょう。

コメント作成の一般的なルール

  • 重要なセクションは、スラッシュ、アスタリスクまたは等号の連続を使用して囲みます。

    等号で囲まれた重要なセクション

  • 1 行のコメントを使用して前提や既知の問題、ロジックに関するインサイトについて説明するか、自動化セグメントをマークします。

    1 行のコメントを使用して、前提を説明

    既知の問題とロジックに関するインサイトを説明。

  • コメントはわかりやすく記入します。

    悪いコメントの例

    良いコメント

  • 誤ったタスク行を発見した場合は、必ず「//FIX THIS」などの共通のフレーズを含むコメントを使用します。コメントを使用しない場合は、タスクのその部分を削除するか、作成し直します。
  • コメントをフィルタリングできるように、Task-List のキーワード フラグを使用してコメントを作成します。例:
    // TODO: Place database command here
    // UNDONE: Removed keystroke command due to errors
                                here
  • 最終的な実稼働バージョンには、無効にしたタスク行を残さないようにします。無効にしたタスク行は必ず削除します。
  • コメントを書く際には、各コマンド ブロックの使い方ではなく、そのブロックを作成した理由と機能に重点を置いて記述するようにします。特定のソリューションやアプローチを選んだ理由と、達成しようとしている目的が読み手に伝わるようにコメントを残します。一般的なソリューションで問題が発生したため別のソリューションを選択した場合は、その点についても説明します。