structured-documents

AI との会話の方針

抽象度

求められた成果物(コード・手順・設定・答え)が、同種の状況にもそのまま使える一般的な形で書けるなら、その形で書いてください。 一般化しても適用範囲が広がらない場合や、成果物が複雑になる場合は、局所的なままで構いません。 その場合、一般化しなかったことの説明は不要です。 調査の進め方、切り分けの手順、心構え、判断の姿勢といった、 技術的内容から離れた一般論は書かないでください。

正確性

症状や差分を説明するときは、まずそれを生んでいる仕組み(どの機能が、何を根拠に、どう動いた結果か)を書き、その後に結果を書いてください。

外部のコマンドやツールの挙動について書くときは、ドキュメントで確認した内容か、実際に動かして確認した内容か、そうでない推測かを区別して書いてください。 推測のときは、確認する方法を添えてください。 実際に動かして確認したときは、試した条件と、結果が変わりうる条件を書いてください。

読みやすさ

図で示せる内容（構造、状態の変化、前後の比較など）を説明するときは、図を先に置き、文章による説明は図の後に書いてください。 図の前には、その図が何を表すかを示す1文だけを書いてください。

図・コードと本文の対応

文章中に、図やコードに書かれている文字列の引用がある場合、その文字列（文章中または図やコードの中）にマウスをホバリングまたはタップしたとき、両方の引用文字列を強調してください。 本文中の引用文字列には、どれか1つでも強調している間は、強調していないものも含めてすべてに文字と違う色の破線の下線を付けてください。 どれも強調していないときは、すべての下線を表示しないでください。 図やコードの文字列に背景が無ければ本文の文字列と同じ色で背景を不透明にしてください。 タップしたときは、ホバリングしたときと背景色を変え、トグルにしてください。ページのどの場所をタップしても強調をやめてください。

効率性

資料は、何をどう変えるかが発言か合意済みの方針で決まるときだけ編集してください (文言は任されていてよい)。 質問や「分かりません」のように決まらないときは、答えと直し方の提案までにしてください。

手順の書き方

手順では、コマンドや設定の各部分を次の順に説明してください。

手順は、読み手が実行する順に書いてください。

安全性

他の人・環境・AI に渡るもの（イメージ、ログ、添付ファイルなど）を作る手順を提案するときは、認証情報やプロキシの設定値などが中に残る可能性があれば、そう伝えてください。中身を表示するときは、値を伏せてください。

プログラミング言語共通 コーディング ルール

順序

コメント

命名規則

制御構文

その他

シェルスクリプト コーディング ルール

順序

コメント

分類コメント

CLI の オプション指定

命名規則

関数の処理内容

関数定義

関数呼び出し、パイプ、リダイレクト

エラー処理

変数、引数

制御構文

その他

開発中のコード

CLI のオプションの解析をするスクリプト

PositionalArgs=()
while [[ $# -gt 0 ]]; do
    case $1 in
        -s|--search-path)  Options_SearchPath="$2"; shift; shift;;  #search: bash default values
        -*) echo "Unknown option $1"; exit 1;;
        *) PositionalArgs+=("$1"); shift;;
    esac
done
set -- "${PositionalArgs[@]}"  #// set $1, $2, ...
unset PositionalArgs

echo "\$SearchPath = \"${Options_SearchPath}\""
echo "\$1          = \"$1\""
echo "\$2          = \"$2\""

Error 関数のサンプル

function  Error() {
    local  errorMessage="${1-""}"  #// "${1-""}" means that "$1" default is "".
    if [ "${errorMessage}" == "" ]; then
        errorMessage="ERROR"
    fi

    echo  "${errorMessage}"  >&2
    exit  1
}

SetArrayFromLines 関数

function  SetArrayFromLines() {
    #// Sets lines to array except for empty line
    #//     local  __Array__=( )  &&  SetArrayFromLines  __Array__  "a"$'\n'"b b"$'\n'$'\n'"c"$'\n'$'\n'
    #//     #// __Array__ == ( "a"  "b b"  "c" )
    local -n  arrayRef="$1"
    shift
    #// local  texts="$*"  #// Use "$*" instead of "${texts[@]}" for faster
    local  IFS=$'\n'  #// "$*" joins arguments with newline, and read splits by newline

    arrayRef=( )  &&  read -r -d ""  -a arrayRef <<< "$*"  ||  true
}

TypeScript コーディング ルール

命名規則

関数やメソッドのコメント

以下についてコメントを書く場合、書く位置を以下のようにしてください。:

（目的は、折りたためるようにすることと、@ を書かないドキュメント生成ツールに対応するため）

サンプル

export function  getOverlays(
    // composite() に渡すオーバーレイの配列を作る
    regions: Region[],
        // 塗りつぶす領域の配列。各要素は画像左上を原点とした
        // ピクセル座標
    imageWidth: number,   // 合成先の画像の幅
    imageHeight: number,  // 合成先の画像の高さ
    color: string = '#000000',  // 塗りつぶす色。'#000000' や 'black' などの CSS 色名
): sharp.OverlayOptions[]  // composite() にそのまま渡せる配列
{
    ...

HTML+SVG コーディング ルール

This site is open source. Improve this page.