Pythonコードの注釈規範コードの実例解析

一、コードコメント紹介

注釈はコードの解釈と説明であり、その目的はコードをより簡単に知ることができるようにすることである。

コメントは、プログラムを作成する際に、プログラムを書く人からステートメント、プログラムセグメント、関数などの説明やヒントを与えられ、プログラムコードの読み取り可能性を高めることができます。

処理ロジックのコードにおいて、ソースプログラムの有効注釈量は20%以上でなければならない。

二、コードコメント分類
行のコメント:記号の後の行はコンパイルされません(表示)
ブロックコメント：ブロックの注釈記号の中間部分はコンパイルされません。
三、pythonコードの注釈基礎
Pythonでは、菗を使って単行コメントを表します。単一の行のコメントは、コメントされたコードラインの上に単独の行として置いてもいいし、ステートメントや表式の後に置いてもいいです。以下の例：
name='xiaoohong'葃单行コメント
同前の注釈
name='xiaohong'
Pythonでは、3つのシングル引用符または3つのダブル引用符を使用して、複数のコメントを表します。コメントで多く書けない場合は、以下の例があります。
''
これは3つのシングルクォーテーションマークを使った複数行のコメントです。
''
“”
これは三つの二重引用符を使った複数行のコメントです。
“”
四、DocStringsの紹介と使用
4.1 DocStringsの紹介
文書の文字列
は、ドキュメントプログラムを説明するための重要なツールです。
4.2 pythonでDocStringsを使用する
関数の最初の行には、一対の3つの単引用符''または一対の3つの二重引用符''を使用して、ドキュメントの文字列を定義します。docを使って関数の文書の文字列属性を呼び出すことができます。
作成例は以下の通りです。

def add(num1,num2):
  """           

  :param num1:   1
  :param num2:   2
  :return:  
  """
  return num1 + num2

print( add.__doc__ )

備考：DocStrings文書の文字列使用慣例：その最初の行は関数機能を簡単に説明し、第二行は空欄で、第三行為関数の具体的な説明。
五、DocStringsはよく編纂スタイルを使います。
5.1リリーススタイル
これは今流行しているスタイルで、reSTスタイル、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
"""

六、コメント経験

コメントは多ければ多いほどいいです。一目瞭然のコードにはコメントを追加する必要はありません。

は、複雑な動作については、動作開始前に対応する注釈を記入するべきである。

は、一目瞭然ではないコードに対して、コードの後に注釈を追加するべきである。

は絶対コードを記述しないでください。普通コードを読む人はみんなPythonの文法を知っていますが、コードは何をしますか？
以上が本文の全部です。皆さんの勉強に役に立つように、私たちを応援してください。