Pythonコードのコメント仕様コードを解析する

##1. コード コメントの概要

コメントはコードの説明や説明であり、コードを理解しやすくすることが目的です。
• コメントは、プログラマがステートメント、プログラム セグメント、関数などについての説明やヒントを記述することにより、プログラム コードの可読性を向上させることができます。
• 処理ロジックを含むコードでは、ソースプログラム中の有効なコメントの量が 20% 以上必要です。

関連する学習の推奨事項:

Python ビデオ チュートリアル

2. コード コメントの分類

行コメント：シンボル以降の行はコンパイル（表示）されません。

ブロックコメント：ブロックコメントシンボルの途中の部分コンパイルは行われません。 コンパイル

#3. Python コードのコメントの基本

## は、Python で単一のコードを表すために使用されます。 -行のコメント。単一行コメントは、コメント対象のコード行の上、またはステートメントまたは式の後に別の行として配置できます。次の例:

name = 'xiaohong' # 単一行のコメント

# 単一行のコメント

name = 'xiaohong'

Python で複数行のコメントを示すには、3 つの一重引用符または 3 つの二重引用符を使用します。次の例のように、コメントが多すぎて書ききれない場合に使用されます。

'''

これは 3 つの一重引用符を使用した複数行のコメントです
'' '

"""

これは 3 つの二重引用符を使用した複数行のコメントです
""

4。 DocStrings の概要と使用法

4.1 DocStrings の概要

ドキュメント文字列

は、解釈するための重要なツールです。ドキュメント プログラム。プログラムのドキュメントがよりシンプルで理解しやすくなるようにします。

4.2 Python での DocStrings の使用

3 つの一重引用符 ''' のペア、または 3 つの一重引用符のペアを使用します。関数本体の 1 行目 ダブルクォーテーション「"」で docstring を定義します。doc (二重アンダースコアに注意) を使用して、関数内で docstring 属性を呼び出すことができます。

記述例は次のとおりです。

def add(num1,num2):
  """ 完成传入的两个数之和

  :param num1: 加数1
  :param num2: 加数2
  :return: 和
  """
  return num1 + num2

print( add.__doc__ )

備考: DocStrings ドキュメント文字列の使用規則: 最初の行は関数の機能を簡単に説明し、2 行目は空白で、3 行目は関数の具体的な説明です。 ##5. DocStrings の一般的な記述スタイル

5.1 reST スタイル
これは現在人気のあるスタイルであり、reST スタイル、DocStrings の王立形式です。 Sphinx は比較的コンパクトです。

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

5.2 Google スタイル

"""
This is a groups style docs.

Parameters:
 param1 - this is the first param
 param2 - this is a second param

Returns:
 This is a description of what is returned

Raises:
 KeyError - raises an exception
"""

5.3 Numpydoc (Numpy スタイル)

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
 the 1st param name `first`
second :
 the 2nd param
third : {'value', 'other'}, optional
 the 3rd param, by default 'value'

Returns
-------
string
 a value in a string

Raises
------
KeyError
 when a key error
OtherError
 when an other error
"""

6. アノテーションの経験

コメントは多いほど良いです。一目でわかるコードの場合は、コメントを追加する必要はありません。複雑な操作の場合は、対応するコメントを追加する必要があります。操作を開始する前に記述する必要があります。

一目でわかりにくいコードについては、コードの後に​​コメントを追加する必要があります。
• コードについては絶対に記述しないでください。通常、コードを読んだ人は知っています。 Python の構文は理解できても、コードが何をしているのかがわからない
• 関連学習の推奨:
• プログラミング ビデオ

以上がPythonコードのコメント仕様コードを解析するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。