函數文檔中動詞的單數第三人稱？

02-14

&>&>&> help(str.find) Help on method_descriptor:
find(...) S.find(sub [,start [,end]]) -&> int Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.
Return -1 on failure.
以上來自python27的幫助。問題是這個Return應不應該加一個s?

@Belleve的猜測有可能是文檔作者這樣寫的原因，但並不符合英語規範。省略主語時情態動詞並不能一併省略，要這樣寫也應該是「Will return ...」。

函數起名和文檔里的人稱問題是個廣泛存在的問題，也沒有權威規範，在StackOverflow問這樣的問題會被當做opinion-based關掉。在實際應用里，大多數文檔都貫徹第三人稱單數，而函數起名則是動詞原形和三單混用：

class Foo { void DoSomething(); bool IsInitialized(); }

一般解釋是前者是動作，所以用第二人稱命令句；後者是查詢，所以用第三人稱陳述或疑問句。但這解釋不了GetXyz而不是GetsXyz，有人說是為和SetXyz對稱的特例。

而Ruby里查詢類方法也用動詞原形，松本行弘在FAQ里是這樣解釋的：

|"responds_to?" probably makes more sense to English speakers than |"respond_to?".


Maybe.  But Im Japanese.  Ruby is not English.  Its the basic naming

rule to avoid third person singular form in the standard libraries.
  you = Human.new

  if you.respond_to?(:knock)

    ...

  end

buddies = member.collect{|x| x.friend_of?(me)} buddies.respond_to?(:select)

扯遠了……回到題主說的文檔，解釋成命令語氣還是比較奇怪的，所以確實應該加-s。

你可以理解成

省略了 It will... 或者 Calling this function will...

你可以給人家提一個issue，或者fork過來改好了再pull request過去啊