警告文「D401: First line should be imperative: 」 の意味はなんでしょうか？

Question

Atomというエディタにlinterパッケージを入れて、pythonの勉強をしています。
警告文がとても不思議で、どう捉えればいいのかが解らなくて相談します。

こちらのサイトにある、「D401: First line should be imperative: 」についてです。
https://github.com/PyCQA/pydocstyle/issues/68

Weblio翻訳ですと、「1本目の線は避けられなくなければなりません」となります。
試しにこんなコメントを書いてみました。

def hogemethod(size):
    """This is a Pen."""

この時の警告文は、

D401 First line should be in imperative mood ('Thi', not 'This') [pep257]

となりました。
というわけで、こんな感じに修正すると、警告が消えました。

def hogemethod(size):
    """Thi is a Pen."""

警告は消えましたが、とてもこれが正しい文章だとは思えないのです。
この警告文は、何を目的として、どう修正せよと言っているのでしょうか・・・？

Answer 1

linter-pydocstyleというパッケージをお使いでしょうか？以下、それが前提でお話しします。

まず、「D401: First line should be in imperative mood」というのは「(ドキュメントの)1行目は命令文であるべきです。」と言う意味です。"Do it."とか"Return 0."とかそういうのであるべきということです。pydocstyleはこれを検知して、命令文じゃないと警告をしているというものになります。

が、チェックの仕方の実装はかなりいい加減です。

実装はこちらです。何をしているかというと、最初の行の最初の単語が"s"で終わる(ただし、"ss"では終わらない)場合は、警告を出すとしています。単純に"This"の最初の"s"に引っかかっただけで、命令文であるとかそういったものは一切考慮していません。質問で挙げていただいたIssueでも上がっているのですが、"""Focus the application."""という正しい命令文であっても引っかかります。

linter-pydocstyleパッケージの設定で無効にする警告が選べますので、警告がうざいようであれば、D401を無効にすることをお勧めします。そもそも、日本語のドキュメントは一切考慮されていませんので、パッケージ自体を無効にしてもいいかと思います。linter-pydocstyleはドキュメント部分しか関係ありません。

Comments

[usugita_san]

すみません、Linter Pylama というのを使ってました。
D401を速攻で無効にしました。これ全然意味ない警告っすね・・・。
ソースまで教えて頂けまして、ありがとうございました。

Answer 2

意訳ですが、「体言ではなくて用言で説明しろ」ということだと思います。より砕いて言うと「何をするのか書け」ということです。Thisから始まるdocstringはほとんど体現であるから、linterで禁止しているのだと思われます。

以下のようなコメント(docstring含む)はたいてい無意味であるから避けるべきだとされています。

def pen():
   '''これは筆記具についての関数です'''
   ''' This is a pen '''

for i in a:
  # これはforループです

このような「関数の自己紹介」ではなくて「何をするのか説明しろ」、ということでしょう。

def pen():
    ''' 筆記具の状態を取得する '''
    ''' Return the pen state '''

for i in a:
    # すべての筆記具についてhogehogeを行う

--追記
関数やメソッドについては用言にするのが普通ですが、クラスやモジュールについては体現で説明することも許されてると思います。私はそのlinterを使っていないのですが、クラスについては同じdocstringでも警告を出さないと思いますよ。

Answer 3

確認になりますが、
記載されたpythonコードでエラーになっているのではないんですよね。。
ヒアドキュメントだけ書いても何に使うか解釈できなくてエラーになっているのではないのでしょうか。

また、根本的な解決ではないですが、
Linterを変えてみてはいかがでしょうか。
私の環境では発生しませんでした。

[Packages]
linter
linter-pylint

Comments

[usugita_san]

ありがとうございます。Linter Pylama をやめて、他の物を探してみようと思います。