Почему императивное настроение важно для шнурков?

Question

Код ошибки D401 для pydocstyle гласит: First line should be in imperative mood.

Я часто сталкиваюсь со случаями, когда я записываю строку документации, получаю эту ошибку с помощью моего линтера и переписываю ее - но две строки документации семантически идентичны. Почему важно иметь императивное настроение для струн документов?

Answer 1

Из самой строки документа check_imperative_mood:

  """D401: First line should be in imperative mood: 'Do', not 'Does'.

   [Docstring] prescribes the function or method's effect as a command:
    ("Do this", "Return that"), not as a description; e.g. don't write
    "Returns the pathname ...".

(Мы проигнорируем иронию, что сама эта строка документации провалит тест.)

Answer 2

Почему это важно? Потому что это явное соглашение для Python строк документации, как описано в PEP 257 . В этом нет ничего особенного - для меня не очевидно, что одно из «Умножить два целых числа и вернуть произведение» и «Умножить два целых числа и вернуть произведение» явно лучше, чем другое. Но это явно указано в документации.

Answer 3

Рассмотрим следующий пример кандидата для строки документа:

Make a row from a given bit string or with the given number of columns.

В английском языке sh это полное грамматическое предложение, которое начинается с заглавной буквы и заканчивается точкой. Это предложение, потому что в нем есть субъект (неявно «вы»), объект «строка» и предикат (глагол) «make».

Теперь рассмотрим альтернативу:

Makes a row from a given bit string or with the given number of columns.

В английском sh это не грамматически. Это прилагательная фраза, поэтому она не должна начинаться с заглавной буквы и не должна заканчиваться точкой. Давайте исправим эту проблему:

makes a row from a given bit string or with the given number of columns

Как прилагательная фраза, ее предшественник - ее цель - не является явным. Конечно, мы знаем, что этот элемент «зашнурован», но грамматически он болтается. Это проблема. Эстетически это некрасиво, и это еще одна проблема. Итак, мы исправили одну проблему и добавили еще две.

Для людей, которым небезразлично ясное, однозначное общение в грамматическом английском языке sh, первое предложение явно лучше. Я предполагаю, что именно поэтому Pythonistas выбрал первое предложение. Таким образом, «строки документации должны быть полными грамматическими предложениями, особенно в императивном настроении».

Answer 4

Для согласованности. Это может быть связано с тем, что сообщения о фиксации, которые git автоматически создает, как и при фиксации слиянием, также используют императивное настроение.