ソースコードからドキュメントを自動生成して、プログラミングを快適に!

Masa

2024年5月16日 18:06

「仕様書？ないよ。うちはソースコードが仕様書だから。」
「その仕様はソースコード見て！」

こんなことを言われたことはありませんか？

担当の開発者の頭の中のみ仕様書がある状態で、後から入ったメンバーが困ったりすることがあります。そんな状況を改善するために、ちょっとツールを作ってみました。

前回作成したマークダウン形式でのソースコードの一括抽出ツールがあるので、新たにソースコード定義書やデバッグドキュメントの生成機能を実装しました。これにより、より効率的なコーディング生活を実現するはずです。

新機能で何ができる？

このツールは、以前からマークダウン形式でソースコードをすぐにペーストできる状態にする機能がありました。今回のアップデートで、次のような新機能が追加されています。

ソースコード定義書の生成

コードの内容や機能を説明する文書を自動で作成
プロジェクトの文書管理がラクに

デバッグドキュメントの自動生成

バグ修正に役立つ詳細な情報を含んだドキュメントを自動で作成
トラブルシューティングが素早く解決

".codeignore"で必要なファイルだけ管理

不要なディレクトリやファイルを除外する設定ファイル
管理するコードを自由にカスタマイズ可能

PlantUMLを利用した図解

UMLを利用した処理を可視化
シーケンス図やER図を作成

実行例

以下のコマンドを実行することで、指定されたディレクトリ内のPythonファイルがマークダウン形式で出力され、同時にソースコード定義書とデバッグドキュメントが生成されます。

python codeland.py /path/to/your/code/ .py -p -c -d

下記のようなソースコード仕様書が生成されます。

## 1. ソースコードのフォルダ構成と内容

- `main.py`: プロジェクトのエントリーポイントとなるメインファイル。ユーザーが実行することで、数値の基本的な算術演算を行う。
- `lib/`: 算術演算を行う関数を含むフォルダ。
  - `arithmetic.py`: 加算、減算、乗算、除算の関数を提供するファイル。

### フォルダ構成
```
project/
│
├── main.py
└── lib/
    └── arithmetic.py
```

### ファイル間の処理のやり取り
```plantuml
@startuml
actor User
User -> main.py : Execute
main.py -> arithmetic.py : import arithmetic
main.py -> arithmetic.py : add(a, b)
main.py -> arithmetic.py : subtract(a, b)
main.py -> arithmetic.py : multiply(a, b)
main.py -> arithmetic.py : divide(a, b)
@enduml
```

## 2. ソースコードの内容と説明

### `main.py`
- **役割**: プロジェクトのエントリーポイント。ユーザーが実行することで、数値の基本的な算術演算を行う。
- **主要な関数**:
  - `main()`: プログラムのエントリーポイント。変数 `a` と `b` を定義し、それらに対して加算、減算、乗算、除算を行う。結果は標準出力に表示される。

#### `main()`関数の詳細
```python
def main():
    a = 10
    b = 5

    print(f"{a} + {b} = {arithmetic.add(a, b)}")
    print(f"{a} - {b} = {arithmetic.subtract(a, b)}")
    print(f"{a} * {b} = {arithmetic.multiply(a, b)}")
    print(f"{a} / {b} = {arithmetic.divide(a, b)}")

if __name__ == "__main__":
    main()
```
- **処理の流れ**:
  1. 変数 `a` と `b` をそれぞれ 10 と 5 に設定。
  2. `arithmetic` モジュールの関数を使用して、加算、減算、乗算、除算を行う。
  3. 結果を標準出力に表示。

### `lib/arithmetic.py`
- **役割**: 基本的な算術演算を行う関数を提供する。
- **主要な関数**:
  - `add(a, b)`: 2つの数の和を返す。
  - `subtract(a, b)`: 2つの数の差を返す。
  - `multiply(a, b)`: 2つの数の積を返す。
  - `divide(a, b)`: 2つの数の商を返す。除数が0の場合はエラーを発生させる。

#### `add(a, b)`関数の詳細
```python
def add(a, b):
    """2つの数の和を返す"""
    return a + b
```
- **説明**: 2つの数 `a` と `b` の和を計算し、結果を返す。

#### `subtract(a, b)`関数の詳細
```python
def subtract(a, b):
    """2つの数の差を返す"""
    return a - b
```
- **説明**: 2つの数 `a` と `b` の差を計算し、結果を返す。

#### `multiply(a, b)`関数の詳細
```python
def multiply(a, b):
    """2つの数の積を返す"""
    return a * b
```
- **説明**: 2つの数 `a` と `b` の積を計算し、結果を返す。

#### `divide(a, b)`関数の詳細
```python
def divide(a, b):
    """2つの数の商を返す（除数が0の場合はエラーを発生させる）"""
    if b == 0:
        raise ValueError("除数には0を指定できません")
    return a / b
```
- **説明**: 2つの数 `a` と `b` の商を計算し、結果を返す。除数 `b` が0の場合は `ValueError` を発生させる。

### 処理の流れ
```plantuml
@startuml
start
:main.pyを実行;
:変数aとbを設定;
:加算を実行;
:減算を実行;
:乗算を実行;
:除算を実行;
:結果を表示;
stop
@enduml
```

この仕様書は、提供されたソースコードに基づいて作成されました。各ファイルの役割と処理の流れを理解することで、プロジェクト全体の構造と機能を把握することができます。

PlantUMLを使って、シーケンス図も図表にしてくれています。

デバッグドキュメントは下記の通りです。

## 1. デバッグ結果

### `main.py`
#### 問題点1
- 概要: `lib`ディレクトリがモジュールとして認識されない可能性がある。
- 原因: `lib`ディレクトリに`__init__.py`ファイルが存在しないため、Pythonがこのディレクトリをモジュールとして認識しない。
- 修正方針: `lib`ディレクトリに空の`__init__.py`ファイルを追加する。

修正後のコード:
```python
# lib/__init__.py
# 空のファイル
```

- 説明: `__init__.py`ファイルを追加することで、`lib`ディレクトリがモジュールとして認識され、`from lib import arithmetic`が正しく動作するようになる。

### `lib/arithmetic.py`
#### 問題点2
- 概要: `divide`関数で除数が0の場合にエラーメッセージが日本語で書かれている。
- 原因: エラーメッセージが日本語で書かれているため、国際化対応が不十分。
- 修正方針: エラーメッセージを英語に変更する。

修正後のコード:
```python
def divide(a, b):
    """2つの数の商を返す（除数が0の場合はエラーを発生させる）"""
    if b == 0:
        raise ValueError("Division by zero is not allowed")
    return a / b
```

- 説明: エラーメッセージを英語に変更することで、国際化対応が進み、より多くのユーザーにとって理解しやすくなる。

### `main.py`
#### 問題点3
- 概要: `main`関数内での変数`a`と`b`がハードコードされている。
- 原因: ユーザーが異なる値を入力できないため、柔軟性が欠けている。
- 修正方針: コマンドライン引数を使用して、ユーザーが`a`と`b`の値を指定できるようにする。

修正後のコード:
```python
import sys
from lib import arithmetic

def main():
    if len(sys.argv) != 3:
        print("Usage: python main.py <num1> <num2>")
        return

    try:
        a = float(sys.argv[1])
        b = float(sys.argv[2])
    except ValueError:
        print("Please provide two valid numbers.")
        return

    print(f"{a} + {b} = {arithmetic.add(a, b)}")
    print(f"{a} - {b} = {arithmetic.subtract(a, b)}")
    print(f"{a} * {b} = {arithmetic.multiply(a, b)}")
    print(f"{a} / {b} = {arithmetic.divide(a, b)}")

if __name__ == "__main__":
    main()
```

- 説明: コマンドライン引数を使用することで、ユーザーが実行時に異なる値を入力できるようになり、プログラムの柔軟性が向上する。

### `lib/arithmetic.py`
#### 問題点4
- 概要: 関数のドキュメントが不十分である。
- 原因: 各関数のドキュメントが簡潔すぎて、詳細な説明が不足している。
- 修正方針: 各関数のドキュメントを詳細に記述する。

修正後のコード:
```python
def add(a, b):
    """
    2つの数の和を返す

    Parameters:
    a (float): 最初の数
    b (float): 2番目の数

    Returns:
    float: 2つの数の和
    """
    return a + b

def subtract(a, b):
    """
    2つの数の差を返す

    Parameters:
    a (float): 最初の数
    b (float): 2番目の数

    Returns:
    float: 2つの数の差
    """
    return a - b

def multiply(a, b):
    """
    2つの数の積を返す

    Parameters:
    a (float): 最初の数
    b (float): 2番目の数

    Returns:
    float: 2つの数の積
    """
    return a * b

def divide(a, b):
    """
    2つの数の商を返す（除数が0の場合はエラーを発生させる）

    Parameters:
    a (float): 最初の数
    b (float): 2番目の数

    Returns:
    float: 2つの数の商

    Raises:
    ValueError: 除数が0の場合
    """
    if b == 0:
        raise ValueError("Division by zero is not allowed")
    return a / b
```

- 説明: 各関数のドキュメントを詳細に記述することで、関数の使用方法や引数、戻り値についての理解が深まり、コードの可読性とメンテナンス性が向上する。

プログラムの入手

プログラムは下記からダウンロード可能です。

Pythonで書かれており、ソースコード定義書およびデバッグドキュメントの生成には、OpenAIのAPIキーが必要です。

まとめ

この更新により、プログラミング作業の一部をAIが支援することで、開発者はより創造的な作業に集中できるようになります。技術の進化を活用して、より効率的かつ効果的な開発環境を構築しましょう。

この記事が気に入ったらサポートをしてみませんか？