Lao Qi から Python を学ぶ - Python ドキュメント

文書化は重要です。独孤九剣の剣術、易進経の精神術、そして魔除けの剣書が記されたカソックはすべて文書である。私たちどころか、それらの権力者ですらこれらの書類が必要なのでしょうか？したがって、文書化は非常に重要です。

率直に言えば、ドキュメントは Word (これが最も一般的です) などを使用して書かれます (ここでは「待機」という単語に注意してください。テキストを編集するときに使用する vim ツールを含め、一般的ではないツールはすべて省略されています)テキスト書き込みツールにはテキスト コンテンツが含まれますが、テキスト ファイルに限定されません。ちょっと冗長ですが、正確に言うと冗長にするのが目的です（笑）。確かにウィキペディアから、より説得力のある定義を考え出す方が良いでしょう。

コードをコピー コードは次のとおりです:

ソフトウェア ドキュメントまたはソース コード ドキュメントは、ソフトウェア システムとそのソフトウェア エンジニアリング プロセスに関連するテキスト エンティティを指します。ドキュメントの種類には、ソフトウェア要件ド​​キュメント、設計ドキュメント、テストドキュメント、ユーザーマニュアルなどが含まれます。要件文書、設計文書、およびテスト文書は通常、ソフトウェア開発プロセス中に開発者によって作成されますが、ユーザーマニュアルなどの非手順文書は専門の非技術者によって作成されます。

Barker の定義によれば、初期のソフトウェア ドキュメントは主にユーザー マニュアルを指し、ドキュメントはシステムの使いやすさを向上させるためにソフトウェア システム インターフェイス要素の設計、計画、実装プロセスを記録するために使用されます。 Forward は、ソフトウェア ドキュメントはソフトウェア エンジニア間のコミュニケーション手段であり、伝達される情報は主に開発中のソフトウェア システムに関するものであると考えています。パルナス氏はドキュメントの権威を強調しており、ドキュメントはソフトウェア システムの正確な説明を提供する必要があると考えています。

要約すると、ソフトウェア ドキュメントは次のように定義できます:

1. ドキュメントはソフトウェア システムについての文書による説明です。 2. 文書はソフトウェア システムを正確に説明する必要があります。
3. ソフトウェア ドキュメントはソフトウェア エンジニア間のコミュニケーション手段です。
4. ソフトウェア要件文書、設計文書、テスト文書、ユーザーマニュアルなど、さまざまな種類の文書があります
5. ドキュメントを表示するには多くの方法があり、従来の文書やグラフの形式、または動的な Web ページの形式にすることができます

では、ここで言及されている Python ドキュメントは何を指すのでしょうか? 1 つの側面は、すべての学習者が Python を学ぶ必要があるということです。Python 開発者 (彼らは全員専門家です) は私たち初心者に何かを提供してくれるでしょうか。私たちはこれらの専門家とコミュニケーションをとり、Python の各関数や命令などの意味や使い方を理解することができるでしょうか。

はい。大きな牛は大きな牛で、用意されており、複数の牛がいます。

Python ドキュメントを表示

このチュートリアルを読んでいる皆さんに心からアドバイスしたいのは、プログラミングを昇華させたいのであれば、ドキュメントを読むことが絶対に必要だということです。ドキュメントは、すべてのチュートリアル、すべての教師、すべての専門家に勝ります。なぜ？その理由は、読者がそれを理解し、経験と洞察を持って初めて理解できます。

Python ドキュメントの URL: https://docs.python.org/2/、これは python2.x です。ここから python3.x のドキュメントも見つけることができます。

Web サイト上のドキュメントを読む以外に方法はありますか?

はい、読者もこのチュートリアルで何度も使用されているもの、つまり dir() と help()

に馴染みがありません。

コードをコピー コードは次のとおりです:

>>> ディレクトリ(リスト)
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__delslice__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', ' __getslice__'、'__gt__'、'__hash__'、'__iadd__'、'__imul__'、'__init__'、'__iter__'、'__le__'、'__len__'、'__lt__'、'__mul__'、'__ne__'、'__new__' 、 '__reduce__'、'__reduce_ex__'、'__repr__'、'__reversed__'、'__rmul__'、'__setattr__'、'__setitem__'、'__setslice__'、'__sizeof__'、'__str__'、'__subclasshook__'、'append'、' count'、'extend'、'index'、'insert'、'pop'、'remove'、'reverse'、'sort']
>>> ヘルプ(list.__mul__)

wrapper_descriptor に関するヘルプ:

__mul__(...)

x.__mul__(n) x*n

この方法は対話モードでよく使用されます。覚えておいてください。

前に述べたように、ドキュメントもあります: ドキュメント、ヘルプ呼び出しは実際にはこの関数の内容です。

コードをコピー コードは次のとおりです:

>>> print(list.__mul__.__doc__) #help(list.__mul__)で表示される内容と同じ
x.__mul__(n) x*n
>>> print(list.index.__doc__) #インデックスのドキュメントを表示

L.index(value, [start, [stop]]) -> 整数 -- value の最初のインデックスを返します。
値が存在しない場合は、ValueError が発生します。

プログラムにドキュメントを追加

自分のプログラムを書くときは、上記の Python ドキュメントの表示と同様の機能があれば、自分のプログラムのドキュメントを何らかの方法で表示でき、見栄えも良くなるでしょう。

これを実現する 1 つの方法は、作成するプログラム内で 3 つの二重引用符または一重引用符をペアで使用し、関連するドキュメントのコンテンツを中央に記述することです。

コードをコピー コードは次のとおりです:

>>> def qiwsir():
... """私は Python が好きです"""
... print "http://qiwsir.github.io"
...
>>> キウサー()
http://qiwsir.github.io

>>> print(qiwsir.__doc__) #このメソッドを使用して、作成した関数内のドキュメントを読み取ります
パイソンが好きです

>>> help(qiwsir) #実際には__doc__を呼び出して表示される内容です

モジュール __main__ の関数 qiwsir に関するヘルプ:

qiwsir()
パイソンが好きです

さらに、ファイルの場合、ファイルのコード操作に影響を与えることなく、関連する命令をファイルの前に置くことができます。

たとえば、.py 拡張子を持つ Python ファイルがあり、その内容は次のとおりです:

コードをコピー コードは次のとおりです:

#!/usr/bin/env python
#coding:utf-8

ランダムにインポート

数値 = ランダム.randint(1,100)

推測 = 0

True の場合:

num_input = raw_input("1 ～ 100 の整数を 1 つ入力してください:")
推測 +=1

num_input.isdigital() でない場合:
print "整数を入力してください。"
elif int(num_input)=100:
print "数字は 1 から 100 までです。"
それ以外:
数値==int(num_input)の場合:
print "OK、あなたは大丈夫です。たった %d だけですので、成功しました。"%guess
休憩
elif 番号>int(num_input):
print "あなたの数字はもっと少ないです。"
elif 番号 print "あなたの数字は大きいです。"
その他:
print 「何か悪いことがあるので、仕事を休みます」

このプログラムは、「while によるループ」で使用される推測ゲームです。このプログラムのドキュメントを作成するには、205-2.py という名前のファイルに保存されます。

コードをコピー コードは次のとおりです:

"""
これはゲームです。
私はQiweiです。
私はパイソンが好きです。
私は自分のウェブサイトで Python の記事を書いています。
私のウェブサイトは http://qiwsir.github.io
です。 Python を無料で学習できます。
"""

#!/usr/bin/env python
#coding:utf-8

ランダムにインポート

数値 = ランダム.randint(1,100)

推測 = 0

True の場合:

num_input = raw_input("1 ～ 100 の整数を 1 つ入力してください:")
推測 +=1

num_input.isdigital() でない場合:
print "整数を入力してください。"
elif int(num_input)=100:
print "数字は 1 から 100 までです。"
それ以外:
数値==int(num_input)の場合:
print "OK、あなたは大丈夫です。たった %d だけですので、成功しました。"%guess
休憩
elif 番号>int(num_input):
print "あなたの数字はもっと少ないです。"
elif 番号 print "あなたの数字は大きいです。"
その他:
print 「何か悪いことがあるので、仕事を休みます」

最後に、非常に良い記事をお勧めしますので、皆さんと共有したいと思います。

Python イントロスペクション ガイド: Python オブジェクトを監視する方法