関数にコメントがないこと(つけ忘れていること)に自力で気づきたいです

特定の機能を実装する際に自分でコメントを書くのを忘れてしまう事が多々あるので、VSCodeの拡張機能などでコメントの無い関数をエラー表示にするなど出来ないか？と思っています。
完璧に防ぎたい訳ではなく、自身で気づけたり、リマインドされればなと思っています。

PHPとJavaScriptを業務で主に使っているのですが、昔からのコードを引き継いで来ているので書き方が統一されておらずバラバラで、コーディングルールやレビューもありません。
そのため自分で気づけるような環境を作りたいと思っています。

上記の方法や他の方法でも構いませんので、いい方法あれば教えていただけると幸いです。

プログラミング言語は
PHP, JavaScript, Pytonです。

エディタはVSCODEです。

よろしくお願いいたします。

TakaiY

2025/10/01 10:09 編集

> コメントの無い関数をエラー表示にするこの「コメント」ってどのようなものを指していますか？具体的な例を追記していただくことできますか？

行動規範の内容に同意します

回答1件

Google Gemini Pro 2.5 による回答

関数へのコメントの付け忘れ、よくありますよね。VSCodeの拡張機能と「リンター」や「静的解析ツール」と呼ばれるものを組み合わせることで、コメントがない関数に警告を表示し、リマインドする環境を簡単に作れます。PHP、JavaScript、Pythonそれぞれで設定方法が少し異なりますので、言語ごとにご紹介します。

JavaScriptの場合：ESLintでJSDocを必須にする

JavaScriptでは、ESLint というツールを使ってコードのルールをチェックするのが一般的です。eslint-plugin-jsdoc というプラグインを追加することで、「JSDoc形式のコメントがない関数は警告」というルールを設定できます。

設定手順

ESLintとプラグインをインストール
ターミナルでプロジェクトのフォルダに移動し、以下のコマンドを実行します。
```
bash
1npm install eslint eslint-plugin-jsdoc --save-dev
```

.eslintrc.json を作成
プロジェクトのルートに .eslintrc.json という設定ファイルを作成し、以下のように記述します。"warn" を "error" に変えると、警告がエラー表示になります。

json
1{
2  "extends": "eslint:recommended",
3  "plugins": ["jsdoc"],
4  "rules": {
5    "jsdoc/require-jsdoc": ["warn", {
6      "require": {
7        "FunctionDeclaration": true, // function myFunction() {}
8        "MethodDefinition": true,    // class MyClass { myMethod() {} }
9        "ClassDeclaration": true,
10        "ArrowFunctionExpression": true, // const myFunc = () => {}
11        "FunctionExpression": true   // const myFunc = function() {}
12      }
13    }]
14  },
15  "parserOptions": {
16    "ecmaVersion": "latest"
17  },
18  "env": {
19    "es6": true
20  }
21}

VSCode拡張機能をインストール
VSCodeの拡張機能マーケットプレイスで「ESLint」を検索し、インストールします。

これで、JSDocコメントがない関数の上に黄色い波線が表示され、マウスオーバーすると「Missing JSDoc comment.」のような警告が見えるようになります。

Pythonの場合：Pylintでdocstringをチェックする

Pythonでは、Pylint や Flake8 といったリンターがdocstring（ドキュメンテーション文字列）の有無をチェックしてくれます。VSCodeのPython拡張機能には、これらのリンターと連携する機能が組み込まれています。

設定手順

Pylintをインストール
ターミナルで以下のコマンドを実行します。
```
bash
1pip install pylint
```
VSCodeでPylintを有効にする
- VSCodeでPython拡張機能をインストールします（ほとんどの場合、インストール済みだと思います）。
- コマンドパレット（Ctrl+Shift+P または Cmd+Shift+P）を開き、「Python: Select Linter」と入力して選択し、表示された一覧から「Pylint」を選びます。
- settings.jsonに以下のような設定が追加され、Pylintが有効になります。
```
json
1"python.linting.pylintEnabled": true,
2"python.linting.enabled": true
```

これで、docstringがない関数やクラスに missing-function-docstring (C0116) のような警告が表示されるようになります。

PHPの場合：PHP_CodeSnifferでPHPDocをチェックする

PHPでは、PHP_CodeSniffer (phpcs) を使ってコーディング規約をチェックするのが一般的です。これを使うと、PHPDocコメント（/** ... */）がない関数を検出できます。

設定手順

PHP_CodeSnifferをインストール
Composerを使ってプロジェクトにインストールするのが簡単です。
```
bash
1composer require --dev "squizlabs/php_codesniffer=*"
```
設定ファイルを作成
プロジェクトのルートに phpcs.xml というファイル名で設定ファイルを作成し、チェックしたいルールを記述します。ここでは「関数のコメントがない」というルール（Squiz.Commenting.FunctionComment.Missing）を指定します。
```
xml
1<?xml version="1.0"?>
2<ruleset name="MyProjectStandard">
3  <description>My Project Coding Standard</description>
4  <autoload>./vendor/autoload.php</autoload>
5
6  <rule ref="Squiz.Commenting.FunctionComment.Missing"/>
7
8  <file>./src</file> </ruleset>
```
VSCode拡張機能をインストール
VSCodeの拡張機能で「phpcs」を検索し、インストールします。拡張機能の設定で、プロジェクト内の phpcs.xml を使うように設定すれば、エディタ上でリアルタイムに警告が表示されるようになります。

導入にあたってのヒント ✨

まずは「警告（Warning）」から: 既存のコードが大量にある場合、いきなり「エラー（Error）」にすると画面が真っ赤になってしまいます。まずは警告レベルで設定し、新しく書くコードや修正するコードからコメントを付けていく習慣をつけるのがお勧めです。
コメントを書きやすくする拡張機能も便利: コメントを書く手間を減らす拡張機能も併用するとさらに効果的です。
- PHP: PHP DocBlocker
- JavaScript / TypeScript: VSCodeに標準で備わっています。関数の上の行で /** と入力してEnterキーを押すと、テンプレートが自動で挿入されます。
- Python: autoDocstring - Python Docstring Generator