入門者が、Python プログラミングにおいて、生成AI(Copilot)を使ってコメントとdocstring を付ける。

以前紹介した、
PyFlo　The beginners guide to becoming a Python programmer
https://pyflo.net/
の中で、「Guided Project 1」をクリックすると、
Flag Creater
https://pyflo.net/flag/
というものがありました。

文化の日も近いので、日の丸を文字で作るプログラムを作ってみました。
Wikipedia で日章旗を調べると、
縦を2とすると横が3、その中央にある円の直径が縦の　3/5 となっています。
縦を 2.0 とすると、横は 3.0 となり、　中央の円の半径は 2 * (3/5) / 2 = 0.6 となります。
半角文字の大きさの比率がだいたい縦：横　2:1 となるので、1行の文字数は旗の左下隅を X-Y平面の原点においたとして、
その座標は、
左上　(0,20) 、 右上　(60,20) 、　
左下　(0,0) 、　右下　(60,0)
としました。変換してそれぞれ、(0.0 , 2.0) 、(3.0 , 2.0)、　(0.0 , 0.0)、(3.0 , 0.0)になります。

これでプログラムを作ってみます。関数も使わない単純なものですが、このプログラムにコメントや docstring を入れるために、 Microsoft Copilot を使いました。

まず、docstring 生成を次のプロンプトで依頼しました。そのとき、プログラムがどのようなものかを簡単に説明する文を陽に入れてみました。

「次のPython プログラムの docstring を生成して下さい。
これは、日章旗を文字で生成するためのプログラムです。
日章旗は、縦の長さを2、幅の長さを3、中央の日の丸の半径を 0.6 になるように作成します。

w = 60
h = 20
a0 = '+' + '-'*(w-1) + '+'
a20 = '+' + '-'*(w-1) + '+'
a = '|' + ' '*(w-1) + '|'

print(a0)
for i in range(1,h):
   y = (h - i) / (h / 2)

   b = a[0]
   for j in range(1,w):
      x = j / (w / 3)

      if ( (x-1.5)**2 + (y-1.0)**2 < 0.36 ) :
         b += '*'
      else:
         b += a[j]
   b += a[-1]

   print(b)

print(a20) 」

Copilot の回答は以下の通りでした。

ここから＝＝＝＝＝＝
もちろん、こちらがあなたのプログラムのためのdocstringです：

def draw_nisshoki():
   """
   This function prints the Japanese national flag (Nisshoki) using ASCII characters.

   The flag's proportions are a height to width ratio of 2:3, with a red circle (the sun)
   in the center. The circle's radius is 0.6, scaled appropriately to fit within the grid.

   The border of the grid is made up of '+' and '-' characters for the top and bottom,
   and '|' characters for the sides. The sun is drawn using '*' characters inside the grid.

   Variables:
   w (int): The width of the grid.
   h (int): The height of the grid.
   a0 (str): The top border of the grid.
   a20 (str): The bottom border of the grid.
   a (str): The side borders of the grid.

   The function uses nested loops to calculate the positions of the '*' characters
   that form the sun based on the coordinates (x, y) within the grid.
   The equation `( (x-1.5)**2 + (y-1.0)**2 < 0.36 )` is used to determine whether
   a particular point should be part of the sun shape or not.
   """
   w = 60
      .................
      （プロンプトで入力したプログラムなので途中省略）
      .................
   print(a20)

＝＝＝＝＝＝ここまで

関数にされてしまいました。しかもなぜか英語でした。これは、docstring は、関数やクラスの中で使うかららしいです。 一応 DeepL で翻訳（少し修正あり）しておきます。

この関数は、日本の国旗（日章旗）をASCII文字で印刷します。

　国旗の縦横比は2:3で、中央に赤い円（太陽）がある。円の半径は0.6で、グリッドに収まるように適切に拡大縮小されています。

　グリッドの境界線は、上下に'+'と'-'、左右に'|'で構成されている。太陽はグリッドの内側に'*'文字を使って描かれます。

　変数

　w (int)： グリッドの幅。
　h (int)： グリッドの高さ。
　a0 (str)： グリッドの上辺。
　a20 (str)： グリッドの下端。
　a (str)： グリッドのサイドボーダー。

　この関数は，ネストされたループを使用して，グリッド内の座標 (x, y) に基づいて太陽を形成する '*' 文字の位置を計算します．

　方程式 `( (x-1.5)**2 + (y-1.0)**2 < 0.36 )` は、特定の点が太陽の形に含まれるかどうかを決定するために使用されます。

プログラムの内容を、ほぼ正確に表してくれていますね。

そこで、今度はこのプロンプトの docstring を　コメント　にして再び Copilot にたずねました。

「次のPython プログラムを説明するための分かりやすいコメントをプログラムに追加して下さい。
これは、日章旗を文字で生成するためのプログラムです。
日章旗は、縦の長さを2、幅の長さを3、中央の日の丸の半径を 0.6 になるように作成します。
（この後のプログラムは同じなので省略）」

Copilot　の回答は以下の通りでした。

ここから＝＝＝＝＝＝
以下に、プログラムにコメントを追加しました。これで、各部分の動作がわかりやすくなると思います。

```python
# 幅と高さを設定
w = 60
h = 20

# 上部と下部の枠線を作成
a0 = '+' + '-'*(w-1) + '+'
a20 = '+' + '-'*(w-1) + '+'
# 空白の行を作成
a = '|' + ' '*(w-1) + '|'

# 上部の枠線を表示
print(a0)

# 高さ分のループを開始
for i in range(1, h):
   # y座標を計算（中心を基準にした相対位置）
   y = (h - i) / (h / 2)

   # 行の開始文字を設定
   b = a[0]
   # 幅分のループを開始
   for j in range(1, w):
      # x座標を計算（中心を基準にした相対位置）
      x = j / (w / 3)

      # 中心からの距離が半径0.6以内なら '*' を追加、それ以外は空白を追加
      if ( (x-1.5)**2 + (y-1.0)**2 < 0.36 ):
         b += '*'
      else:
         b += a[j]
   # 行の終了文字を追加
   b += a[-1]

   # 行を表示
   print(b)

# 下部の枠線を表示
print(a20)
```

このコメントが、プログラムの理解に役立つことを願っています！他に質問があれば教えてくださいね。

＝＝＝＝＝＝ここまで


一言も伝えていないのに、プログラムだけから、

上枠(a0)、下枠(a20)と解釈したり、
「中心を基準にした相対位置」と解釈したり、
if 文で陽に 0.36 としか書いていないのにプロンプトから？「半径0.6」と解釈したりと、

しっかりとコメントしてくれています。これは良いですね。

以上、簡単なプログラムを作成して Copilot でコメントやdocstring を付けてもらいましたが、満足できるものでした。

ということは、Python 入門者は生成AIを活用して自分がプログラミングしたプログラムに対してコメントや docstring　を付けてもらい、それを参考にしてさらに知識を得ることが、かなり有用であると言えそうです。

最後にプログラムを動作させたときの画像を表示しておきます。作成したプログラムは flag.py というファイルです。


docstring は、Python の有用な機能なのは、SimplePrograms で学ぶうちに理解しました。そうであるなら、初心者は生成AIを積極的に活用して docstring を使うという流れになるかもしれませんね。