0

コードにコメントを付けるときによくあるジレンマの 1 つは、引数名をマークアップする方法です。私が何を意味するかを説明します：

def foo(vector, widht, n=0):
  """ Transmogrify vector to fit into width. No more than n 
      elements will be transmogrified at a time
  """

さて、これに関する私の問題は、引数名vector、widthおよびnがそのコメントでまったく区別されておらず、単純なテキストと混同される可能性があることです。その他のオプション:

「幅」に収まるように「ベクトル」を変形します。「n」以下

または多分：

-vector- を -width- に収まるように変形します。-n-以下

あるいは：

:vector: を :width: に収まるように変形します。:n:以下

あなたは要点を理解します。Doxygen のようないくつかのツールはこれを強制しますが、ツールを使用しないとどうなりますか? この言語は依存していますか?

何を使うのが好きですか?

4

4 に答える 4

4

私は個人的に一重引用符を好みます - あなたの最初の例です。下線もイタリック体も使用できない場合に、特定のタイトル/名前付きエンティティを英語のテキストで参照する方法に最も近いようです。

于 2008-12-19T09:20:27.653 に答える
0

私のお気に入りのオプションは、次のように書くことです。

def foo(vector, width, n=0):
  """ Transmogrify 'vector' to fit into 'width'. No more than 'n' 
      elements will be transmogrified at a time

      @param vector: list of something
      @param width:  int
      @keyword n:      int (default 0)
  """

Epydoc recognizes @param (see Epydoc manual), and you can use some fancy regexp to find and print parameters of your function, and hopefully Eclipse will start to show parameters description for Python functions in quick assist some day, and I'm pretty sure that it would follow pattern 

@ <keyword> <paramName> <colon>

とにかく、その日が来たら、@param を @anythingElse に置き換えるのは簡単です。

于 2008-12-19T10:11:08.487 に答える
0

Reuben に同意します。最初の例が最も読みやすいです。

もちろん、それはあなたの個人的な読書習慣にもよります。3 番目の例のスタイルでコメントを読むことに慣れている場合は、そのスタイルが最も読みやすいと感じるかもしれません。

しかし、最初のスタイルは、私たちが日常生活でテキストを読み書きする方法 (新聞や本) に最も近いものです。したがって、これまであなたのコメントを読んだことがない人にとっては、最も読みやすいものです。

于 2008-12-19T09:40:02.963 に答える
0

どちらも使用せず、単に変数の名前をテキストに入れます。または、関数が何をするかを説明するようにテキスト全体を書きますが、その中のパラメーターについては言及しません。これは、関数が何をするかを理解したときに、パラメーターの意味がそれ自体で明確になる場合です。

于 2008-12-19T09:42:43.037 に答える