💨
リーダブルコードチートシートPython版
第Ⅰ部 表面上の改善
2章 名前に情報を埋め込む
明確な単語を選ぶ
- 動作や目的に適した明確な名前を付ける
- 類義語をよく調べる
明確な名前付け
# Bad
def get_page(): # どこからページを取得するのか曖昧
# Good
def fetch_page(): # ネットからページを取得する場合
def download_page():
明確な名前付け
# Bad
def size(): # 何のサイズか分からない
# Good
def height():
def num_nodes():
def memory_bytes():
類義語
send # deliver, dispatch, announce, distribute, route
find # search, extract, locate, recover
start # launch, create, begin, open
make # create, set up, build, generete, compose, add, new
tmpやretvalなどの汎用的な名前を避ける
- エンティティ値や目的を表した名前を選ぶ
-
tmpは生存期間が短く，一時的な保管が最も大切な変数にだけ使う - イテレータが複数ある時は，インデックスにもっと明確な名前を付けるとよい
目的を表した名前
# Bad
retval += v[i] * v[i] # 2乗した値の合計を保存しておく変数
# Good
sum_squares += v[i] * v[i]
一時的な保管
# Good
tmp = right
right = left
left = tmp
一時的な保管が目的ではない
# Bad
tmp = user.name()
tmp += " " + user.phone_number()
# Good
user_info = user.name()
user_info += " " + user.phone_number()
インデックスに名前を付ける
# Bad
for i in range(clubs.size()):
for j in range(members.size()):
# Good
for club_i in range(clubs.size()):
for member_i in range(members.size()):
for ci in range(clubs.size()):
for mi in range(members.size()):
抽象的な名前よりも具体的な名前を使う
# Bad
server_can_start(): # TCP/IPポートをサーバがリッスンできるかどうかを確認するメソッド
# Good
can_listen_on_port():
変数名に情報を追加する
- 変数名に単位を入れる
- 危険や注意を喚起する情報を追加する
変数名に単位を入れる
import time
# Bad
start = time.time()
# 計測したい処理
elapsed = time.time() - start
print("処理時間:", elapsed, "秒")
# Good
start_sec = time.time()
# 計測したい処理
elapsed_sec = time.time() - start_sec
print("処理時間:", elapsed_sec, "秒")
危険や注意を喚起する情報を追加する
# Bad
password # プレインテキストであるため，処理前に暗号化すべき
comment # ユーザが入力したcommentは表示する前にエスケープする必要あり
html # htmlの文字コードをUTF-8に変えた
data # 入力されたdataをURLエンコードした
# Good
plaintext_password
unesvaped_comment
html_utf8
data_ulrenc
名前の長さを決める
- スコープが小さければ短い名前でもいい
- プロジェクト固有の省略形はダメ
- 不要な単語を排除する
スコープが小さい
# Good
if debug:
m = {}
LookUpNamesNumbers(m)
print(m)
プロジェクト固有の省略
# Bad
be_manager # back_end_manager
# Good
eval # evaluation
doc # document
str # string
不要な単語を削除
# Good
to_string(): # convert_to_string():
名前のフォーマットで情報を伝える
- クラス，関数，変数，メンバ変数等で異なるフォーマットを使う
- 基本的にはコーディング規約やプロジェクト内の規約に従う
PythonClass # クラス，例外など
python_class # メソッド，関数，変数
PYTHON_CONST # 定数
3章 誤解されない名前
曖昧な表現を避ける
# Bad
filter(): # 選択するのか除外するのか不明
# Good
select(): # 選択する
exclude(): # 除外する
# Bad
length # 何の長さか不明
# Good
max_lenght # 最大の長さ
max_chars # 文字の長さ
限界値を含めるときはminとmaxを使う
# Bad
CART_TOO_BIG_LIMIT = 10 # 未満か以下か不明
# Good
MAX_ITEMS_IN_CART = 10 # 10以下となる
範囲を指定するときはfirstとlastを使う
# Bad
integer_range(start=2, stop=4) # [2,3] or [2,3,4]
# Good
integer_range(start=2, stop=4) # [2,3,4] 包含していることが明確
包含/排他的範囲にはbeginとendを使う
- 4月中を表す場合，
beginの4月1日は含み，endの5月1日は含まないとなる
# Bad
print_event_int_range(begin="04-01 00:00:00", end="04-30 23:59:59")
# Good
print_event_int_range(begin="04-01 00:00:00", end="05-01 00:00:00")
ブール値の名前
- 頭にis, has, can, shouldなどを付ける
- 否定形ではなく肯定形にする
頭にhasをつける
# Bad
space_left(): # 残りスペースを返すの？
# Good
has_space_left(): # 残りスペースがあればTrue
肯定形にする
# Bad
disable_ssl = False
# Good
use_ssl = True
軽い処理か重い処理かをユーザーに伝える
# Bad
get_mean() # 一瞬で取得するイメージ
size()
# Good
compute_mean() # 計算コストがかかるイメージ
count_size()
4章 美しさ
一貫性のある簡潔な改行位置
# Bad
class PerformanceTester:
wifi = TcpConnectionsSimulator(
500, # kbps
80, # millisecs latency
200, # jitter
1 # packet loss
)
t3_fiber = \
TcpConnectionsSimulator(
4500, # kbps
10, # millisecs latency
0, # jitter
0 # packet loss
)
# Good
class PerformanceTester:
# TcpConnectionsSimulator(throughput, latency, jitter, packet_loss)
# [kbps] [ms] [ms] [parcent]
wifi = TcpConnectionsSimulator(500, 80, 200, 1)
t3_fiber = TcpConnectionsSimulator(4500, 10, 0, 0)
メソッドを使った整列
# Bad
database_connection = database_connection()
error = ""
full_name = expand_full_name(database_connection, "Doug Adams", error)
assert full_name == "Mr. Douglas Adams"
assert error == ""
full_name = expand_full_name(database_connection, "John", error)
assert full_name == ""
assert error == "more than one result"
# Good
def check_full_name(partial_name, expected_full_name, expected_error):
database_connection = database_connection()
error = ""
full_name = expand_full_name(database_connection, partial_name, error)
assert full_name == expand_full_name
assert error == expected_error
check_full_name("Doug Adams", "Mr Douglas Adams", "")
check_full_name("John" , "" , "more than result")
縦の線をまっすぐにする
# Bad
details = request.POST.get('details')
location = request.POST.get('location')
# Good
details = request.POST.get('details')
location = request.POST.get('location')
一貫性と意味のある並び
- 対応するHTMLフォームの
<input>フィールドと同じ並び順にする - 最重要なものから重要度順に並べる
- アルファベット順に並べる
宣言をブロックにまとめる・コードを段落に分割する
# Bad
def suggest_new_friends(user, email_password):
friends = user.friends()
friends_emails = set(f.email for f inf friends)
contacts = import_contacts(user.email, email_password)
contact_emails = set(c.email for c in contacts)
# Good
def suggest_new_friends(user, email_password):
# ユーザーの友達のメールアドレスを取得する
friends = user.friends()
friends_emails = set(f.email for f inf friends)
#ユーザのメールアカウントからすべてのメールアドレスをインポートする
contacts = import_contacts(user.email, email_password)
contact_emails = set(c.email for c in contacts)
5章 コメントすべきことを知る
コメントするべきではないこと
- コードから分かることをコメントに書かない
- ひどいコードを補う補助的なコメント
コードから分かる
# Bad
# 2番目の'*'以降をすべて削除する
name = '*'.join(line.split('*')[:2])
補助的なコメントを記述するのではなく適切な変数名をつける
# Bad
# レジストリキーのハンドルを開放する．実際のレジストリは変更しない．
delete_registry()
# Good
release_registry_handle()
自分の考えを記録する
- 考えを記録する
- コードの欠陥にコメントをつける
- 定数にコメントを付ける
考えを記録
# Good
# このデータだとハッシュテーブルよりもバイナリツリーの方が40%速かった
# 左右の比較よりもハッシュの計算コストの方が高いようだ
コードの欠陥コメント
# Good
# TODO: あとで追加，修正する
# FIXME: 既知の不具合があるコード
# HAXK: あまりきれいじゃない解決策
# XXX: 危険！大きな問題がある
定数にコメント
# Good
NUM_TUREADS = 8 # 値は「>= 2 * num_processors」で十分
MAX_RSS_SUBSCRIPTIONS = 100 # 合理的な限界値．人間はこんなに読めない
IMAGE_QUALITY = 0.72 # 0.72ならユーザはファイルサイズと品質の面で妥協できる
読み手の立場になって考える
- コードを読んだ人が疑問に思うところを予想してコメント
- 読み手が驚くような動作は文書化
- ファイルやクラスには「全体像」のコメント
- 読み手が細部にとらわれないよう，コードブロックにコメントを付け要約
6章 コメントは正確で簡潔に
- 複数のものを指す可能性がある「それ」や「これ」などの代名詞は避ける
- 関数の動作はできるだけ明確に説明する
- コメントに含める入出力の実例慎重に選ぶ
- コードの意図は，詳細レベルでなく，高レベルで記述する
- よくわからない引数にはインラインコメントを使う
- 多くの意味が詰め込まれた言葉や表現を使って，コメントを簡潔に保つ
第Ⅱ部 ループとロジックの単純化
7章 制御フローをよみやすくする
条件式の引数の並び方
# Bad:
if 10 == length:
while bytes_received < bytes_expected:
# Good: 左に期待値や比較対象の式を置く
if length == 10:
while bytes_expected > bytes_received:
if/elseブロックの並び順
- 条件は否定形よりも肯定形を使う
- 単純な条件を先に書く
- 関心を引く条件や目立つ条件を先に書く
肯定形を使う
# Bad
if not debug:
# Good:
if debug
関心を引く条件を先に処理
# Bad
if not url.has_query_parameter("expand_all"):
response.render(items)
else:
for item in items:
item.expand()
# Good: "expand_all"が関心を引く条件なため，これを先に処理する
if url.has_query_parameter("expand_all"):
for item in items:
item.expand()
else:
response.render(items)
三項演算子
- 基本的には誰もが分かりやすいif/elseを使い，三項演算子は簡潔になるときのみ使う
# Bad
return mantissa * (1 << exponent) if exponent >= 0 else mantissa / (1 << -exponent)
# Good
time_str += "pm" if hour >= 12 else "am"
関数から早く返す
# Good: 早期returnを使用する
def contains(str, substr):
if str is None or substr is None: return False
if substr == "": return True
ネストを浅くする
- 関数内で早期
returnを使う - ループ内で
continueを使う
continueを使う
# Bad
for result in results:
if result is not None:
non_null_count += 1
if result != "":
print("considering")
# Good
for result in results:
if result is None:
continue
non_null_count += 1
if result == "":
continue
print("considering")
実行の流れを追えるか？
- スレッド：どのコードがいつ実行されるかよくわからない
- シグナル/割り込みハンドラ：他のコードが実行される可能性がある
- 例外：いろんな関数呼び出しが終了しようとする
- 関数ポインタと無名関数：コンパイル時に判別できないので，どのコードが実行されるかわからない
- 仮想メソッド：object.virtulMethod()は未知のサブクラスのコードを呼び出す可能性がある
使わない方が良い構文
- 基本的にdo/whileは避け，whileループを使う
- 基本的にgotoは使わない
8章 巨大な式を分割する
説明変数
# Bad
if line.split(':')[0].strip() == "root":
# Good: 式を表す変数を使う
user_name = line.split(':')[0].strip()
if user_name == "root":
要約変数
# Bad
if request.user.id == document.owner_id:
# 編集可能
if request.user.id != document.owner_id:
# 読取専用
# Good: 式を変数に代入しておく
user_own_document = request.user.id == document.owner_id
if user_owns_document:
# 編集可能
if not user_owns_document:
# 読取専用
ド・モルガンの法則を使う
# Bad
if not (file_exists and not is_protected):
# Good
if (not file_exists) or (is_protected):
9章 変数と読みやすさ
変数を削除する
- 役に立たない一時変数
- 中間結果を保持する変数
- 制御フロー変数
役に立たない一時変数
# Bad
now = datetime.datetime.today()
root_message.last_view_time = now
# Good
root_message.last_view_time = datetime.datetime.today()
制御フロー変数
# Bad
done = False
while 条件 and not done:
...
if 条件:
done = Ture
continue
# Good
while 条件:
...
if 条件:
break
変数のスコープ縮める
- グローバル変数をできるだけ使わない
- 大きなクラスを小さなクラスに分割する
- 定義の位置を下げる
変数は一度だけ書き込む
- 変数に一度だけ値を設定する
- イミュータブルにする
第Ⅲ部 コードの再構成
10章 無関係の下位問題を抽出する
抽出すべき機能
- 高レベルの目標と関係のない下位の処理
- 純粋なユーティリティコード（文字列操作，ファイルの読み書きなど）
- その他汎用的な機能
- やりすぎには注意
# Bad
def find_closest_location(lat, lng, array):
closest_dist = MAX_VALUE
for i in array:
...
# 高レベルの目標と関係ない複雑な処理
...
if dist < closest_dist:
...
return closest
# Good
def spherical_distance(lat1, lng1, lat2, lng2):
...
# 高レベルの目標と関係ない複雑な処理
...
def find_closest_location(lat, lng, array):
closest_dist = MAX_VALUE
for i in array:
dist = spherical_distance(...)
if dist < closest_dist:
...
return closest
# Bad
user_info = {"username": "...", "password": "..."}
user_str = json.dumps(user_info)
cipher = Chiper("aes_128_cbc", key=PRIVATE_KEY, init_vector=INIT_VECTOR, op=ENCODE)
encrypted_bytes = chpher.update(user_str)
encrypted_bytes += chiper.final()
url = "http://exmaple.com/?user_info=" + base64.urlsafe_b64encode(encrypted_bytes)
# Good
def url_safe_encrypt(obj):
obj_str = json.dumps(obj)
cipher = Chiper("aes_128_cbc", key=PRIVATE_KEY, init_vector=INIT_VECTOR, op=ENCODE)
encrypted_bytes = chpher.update(obj_str)
encrypted_bytes += chiper.final()
return base64.urlsafe_b64encode(encrypted_bytes)
user_info = {"username": "...", "password": "..."}
url = "http://exmaple.com/?user_info=" + url_safe_encrypt(user_info)
11章 一度に1つのことを
- 一度に1つのタスクを行う
- タスクをできるだけ異なる関数に分割，もしくは異なる領域に分割する
12章 コードに思いを込める
- ロジックを明確に説明する
- 既存のライブラリが何を提供してくれるかを理解し活用する
ロジックを明確に説明する
# Bad
if document:
if not is_admin_request() and (document["username"] != SESSION["username"]):
return not_authorized()
else:
if not $is_admin:
return not_authorized()
# Good
if is_admin_request(): # 管理者
pass
elif document and (document["username"] != SESSION["username"]): # 文書の所有者
pass
else: # その他
return not_authorized()
13章 短いコードを書く
- 汎用的なユーティリティコードを作って，重複コードを削除する
- 未使用のコードや機能を削除する
- プロジェクトをサブプロジェクトに分割する
- 定期的にすべてのAPIを読んで，標準ライブラリに慣れ親しんでおく
標準ライブラリに慣れ親しんでおく
# Bad: リストから重複を取り除くため関数を実装
def unique(elements):
temp = {}
for element in elements:
temp[element] = None
return list(temp.keys())
print(unique([2,1,2])) # [2,1]
# Good: set型を使えば解決
print(list(set([2,1,2]))) # [1,2]
14章 テストと読みやすさ
テストを読みやすく保守しやすいものにする
- テストのトップレベルはできるだけ簡潔にする
- 入出力のテストはコード1行で記述できるとよい
入出力のテストを1行で記述
# テスト対象の関数
class ScoredDocument:
def __init__(self):
self.url = ""
self.score = 0.0
def sort_and_filter_docs(docs):
docs.sort(key=lambda x: x.score, reverse=True) # スコアに基づいて昇順にソート
docs[:] = [doc for doc in docs if doc.score >= 0] # 負の値を削除
# Bad
def Test1():
docs = [ScoredDocument() for _ in range(5)]
docs[0].url = "http://example.com"
docs[0].score = -5
docs[1].url = "http://example.com"
docs[1].score = 1
docs[2].url = "http://example.com"
docs[2].score = 4
docs[3].url = "http://example.com"
docs[3].score = -5999
docs[4].url = "http://example.com"
docs[4].score = 3.0
sort_and_filter_docs(docs)
assert len(docs) == 3
assert docs[0].score == 4
assert docs[1].score == 3.0
assert docs[2].score == 1
Test1()
# Good
def check_score_before_after(scores, expected):
docs = [ScoredDocument() for _ in scores]
for doc, score in zip(docs, scores):
doc.score = score
sort_and_filter_docs(docs)
actual = [doc.score for doc in docs]
return actual == expected
check_score_before_after([-5, 1, 4, -5999, 3.0], [4,3,1])
エラーメッセージを読みやすくする
unittestモジュールを使ってより詳細なエラーメッセージを表示する
# Bad
a = 1
b = 2
assert a == b
# エラーメッセージ：aとbの中身が分からない
Traceback (most recent call last):
File "Main.py", line 5, in <module>
assert a == b
AssertionError
# Good
import unittest
class NormalTest(unittest.TestCase):
def test_normal_test(self):
a = 1
b = 2
self.assertEqual(a, b)
if __name__ == '__main__':
unittest.main()
# エラーメッセージ：詳細が表示される
F
======================================================================
FAIL: test_normal_test (__main__.NormalTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "Main.py", line 17, in test_normal_test
self.assertEqual(a, b)
AssertionError: 1 != 2
----------------------------------------------------------------------
Ran 1 test in 0.000s
FAILED (failures=1)
テストの適切な入力値を選択する
- 入力値を単純化
- 1つの機能に複数のテスト
入力値を単純化
# Bad
check_score_before_after([-5, 1, 4, -5999, 3.0], [4, 3, 1])
# Good
check_score_before_after([1, 2, -1, 3], [3, 2, 1])
1つの機能に複数のテスト
# Good: 小さなテストを複数作る方が良い
check_score_before_after([2, 1, 3], [3, 2, 1]) # ソート
check_score_before_after([-10, -1, 3], [3]) # マイナスは削除
check_score_before_after([1, -2, 1, -2], [1, 1]) # 重複は許可
check_score_before_after([], []) # 空の入力は許可
テストの機能に名前を付ける
- クラス名や関数名，状況やバグなどを名前に含める（テストの機能名は長くて良い）
# Bad
Test1()
Test2()
# Good
test_sort_and_filter_docs()
test_sort_and_filter_docs_basic()
テスト容易性の低いコード
- グローバル変数を使っている
- 多くの外部コンポーネントに依存
- コードが非決定的な動作をする
テスト容易性の高いコード
- クラスが小さい．あるいは内部状態を持たない
- クラスや関数が1つのことをしている
- クラスは他のクラスにあまり依存していない
- 関数は単純でインターフェースが明確
Discussion