「よりよいコードを求めて命名について頭をひねる会」のログ

http://www.zusaar.com/event/438105

アプリケーションを作る英語 の著者の西野さんを交えて、クラス名とかメソッド名とか変数名とか命名で困っている課題を1つ以上持ち寄りみんなで一緒に検討する勉強会をしました。

「アプリケーションを作る英語」
電子書籍 http://tatsu-zine.com/books/english4app
紙 http://www.amazon.co.jp/gp/product/4844332848/


はじめに：西野さんからちょっとお話

The Art of Readable Code から第2章と第3章

第2章：名前に情報を詰め込むようにする
どういう情報をつめこむか。
明確な言葉を選ぶ
get は不明確らしい

getPage(url) -> FetchPage(url) や DownloadPage(url)

特色のある（colorful）な言葉を選ぶ
・類語辞典を活用
・いろんなふうに解釈される単語よりも、その意味にしかとれない単語を使う
send -> deliver, dispatch

英語のテクニカルライティング
strong verb を使う（反対は weak verb）

汎用的な名前は避ける

retval だけとか tmp だけとかは良くない
（tmp は本当に短期間だけ使う場合以外は使ってはダメ）

具体的な名前をつける
ServerCanStart() -> CanListenOnPort()

名前に情報を追加する
（名前が長くなりすぎる場合はどうしたらいいのかな？）

・単位のついた値
limit -> max_kbps
angle -> degrees_cw

他の重要な情報を盛り込む
password -> plaintext_password
comment -> unescaped_comment
html -> html_utf8
data -> data_urlenc

頭字語と略語
・プロジェクト特有の略語は良くない
・新加入のチームメンバーがわかるかどうかで略語の使用を判断する

不要な言葉を削除する
ConvertToString() -> ToString()
（メソッドの最初は動詞にしろという、話もあり、、、）

名前の書式で意味を伝える
・アンダースコア、ハイフン、大文字小文字で名前に意味を持たせられる
例 CamelCase, lower_separated, UPPER_CASE


第3章：誤解されない名前をつける

「この名前が別の意味で理解されることはないだろうか？」

filter では、含めるのか除外するのかわかりにくい
select や exclude の方がよい

限界値と範囲の表現（まよったときはこっちがいい）

・max/min : 対象は含む
・first/last: 対象は含む

・begin/end: begin は含むが、end は含まない
未満みたいな英語がないので、end をそういう意味に使おうという著者の提案
（less 〜のようなのはどうなの？）

ブール値の名前
・is, has, can, should など
（is の後が名詞のものは作りやすいが、動詞？助動詞？のときにちょっと悩む）

（誤解されなければ前置詞はなくてもいい？）

使う人の期待に沿う
「get」は軽いアクセサと考える人が多い
getMean() -> すでに計算したものを返すイメージ
computeMean() -> 今からたくさん計算するイメージ
（これはボキャブラリがいるなー）

- get に時間かかるのは想定してない
（即時、副作用があって欲しくない）

i,j,k は許すべきかどうか（forループ）
（for が入れ子になっている場合は i_hoge とかにしたほうがいいらしい）
多重のループをかくとバグを生みやすい

Iteratorを使えばループカウンタによるバグを減らせる
ただし、ループカウンタがほしくなることはある
イテレーターからカウンタが欲しくなることはたまーにある by zaki


作業する場合は動詞からにしてほしい
名詞から始めてもしっくりくるかどうか
ToString は失敗例じゃない？ by amedama

getStringValue() の get を省略したがの Obje-C の StringValue() らしい

本の文はここまで


コード補間があるので、長めにしても問題ない
・名前付き引数に追い出す？
・長すぎるメソッド名はdisられるけど、短すぎて情報量が少ないのも困る
・5、６単語くらいまで？



シソーラス
Thesaurus.com http://thesaurus.com
同意語（synonym）と反意語(antonym)が豊富（だが難しい）

Macmillan http://www.macmillandictionary.com/
英語圏で定評ある辞書（だが難しい）

日本語
Weblio英語類語辞典 http://ejje.weblio.jp/english-thesaurus/
日本語で探せるので便利（だがエントリが変な部分も）

紙
一般的な類語辞典は多い
コンピュータ関連の本：「科学技術英語 動詞はこう使え！」
関数やメソッドの命名で役にたちそう

類語辞典以外の方法
大きめの英和辞典では類語の違いを解説していることがある
オンラインであれば Weblio -> コンピュータ関連辞書（研究社 英和コンピュータ用語辞典、マイクロソフト用語集

Mac には最初からわりといい辞書が入っている by muo

英英辞典（言葉の意味を調べるにはいい）

new TOPGATE office なのか TOPGATE new office なのか
かかるものの直前につけたほうがいい
TOPGATE's new office


命名を変えるのもリファクタリング
リファクタリングにはテストも含まれる


フレームワークを作るとき、ライブラリを作るとき、公開されないメソッドを作る時で意識を変える by muo

API として公開しているかどうか、補間しやすいかどうか、レビューされる by zaki
API を作る段階でインタフェースだけ定義して、コード書くときに補間でしぼれるかどうかとかレビューする by zaki

クラス名、インタフェース名、似たようなクラスがあると絞りづらい by zaki

BaseHoge だと Base でいろいろ出てきちゃうので HogeBase にしたい
だいたい３文字（キャメル頭文字）にしたい by vvakame

パッケージ名は可視性に使って、名前のコリジョンには使わない by vvakame

いろんなパッケージに BaseAdapter があるより socket パッケージのは SocketBaseAdapter のほうがいい by vvakame, zaki

socket パッケージにあるのに Socket がつくのは冗長じゃない？ by amedama

vvakame は書くほう（書くとき）のタイプ数が少ないほうがいい
SocketBaseAdapter は Socket は冗長と思わない、これが冗長になるなら API の設計が変なんじゃない？ by vvakame

IDEのクセに依存しそう

Java は Eclipse に最適化されすぎｗ by amedama

Server side と Client side で違う言語（ruby と Java とか）
の場合にどうしたらいいのか（？）的なやつに関連するもの
https://github.com/ServiceStack/ServiceStack

JSON とかでつながるくらにしておいたほうがいいんじゃない？ by muo



---

「リスナーを登録するメソッドについて」 by esmasui
addListener(), registerListener()
add と register の使い分けがわからない

英語的な意味で

addListener <--> removeListener
registerListener <--> unregisterListener

register は紙にかくイメージ by amedama
register は１個、Listener が複数の場合は add
set は登録するイメージがない by amedama
set のときは１個のイメージ

add というと後ろにコレクションがあって複数追加できるイメージ by zaki
append だとくっついて１個のリスナーになってしまうイメージ

１個 -> setListener
複数 -> addListener
register はなんかエラそう by itog
システムに登録するようなアプリ全体のなにかに登録する場合は register


---

なになにのために〜する
例: updateForGame()
updateGame(Game game)
ゲームをアップデートするのではなく、自分がアップデートする？

そもそもゲームをアップデートするわけではない -> uploadGame(Game game) では？

こういうのを多用しているんだけど、これでいいのかな？

vvakame update For Game? -> わかめがアップデートする

update は他動詞のみ

syncGameStatus() とか by amedama
update だと漠然としている。もっと特定の用途を表すメソッドを使うべきでは。

結論は...
自動詞か他動詞か調べよう！
他動詞の場合は、動詞+目的語(目的語) の形がよいのでは
update は抽象的なので、もっとあいまいじゃない動詞を使おう！

for が入る文を調べたかったら英辞郎とかでワイルドカードを使って、for と組み合わせて検索するのがいいのでは by nishinos
英辞郎で "update for {1}" で検索するなど


----

ここからはファンタジー

SnoreEvent というクラス名はありか？

そもそもこれイベントとなの？ by corosuke

よくあるのはEventListenerに登録するときのイベント名によくつかうよね by zaki

「命名で悩んでいる場合、APIの設計がうまくないことがよくある」 by muo

これだけで使い方わかるからいいんじゃない？ by amedama
WakeUpEvent と AwakeEvent があって AwakeEvent はいつ呼ばれるの？

ファンタジー終わり


---

チームでのさじ加減むずい by muo

プログラミングについても英語についても共通認識をどこに設定したらいいのか
（さっきいろいろ聞いたので、、、）

G社さんはレビューでチェックしている。常識に外れない程度になっている。
新しい API を作るときは全体の整合性を保つようにチェックする機関がある（らしい？）
コーディングのスタイルガイドがある
https://www.google.co.jp/search?q=google+coding+conventions&aq=1&oq=google+coding+c&sugexp=chrome,mod=1&sourceid=chrome&ie=UTF-8&qscrl=1

google coding conventions などでググれ

http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml


---

コミットログの書き方に悩んでいます by vvakame

なぜそうしたのか、というのを長々と書きたい時に英語力が低いので、
どういうことを書いたほうがいいのかわからない。
自分の中では合理的な理由があるんだけど、日本語ならかけるけど英語だとうまく書けない

箇条書きにしてみてはどう？ by nishinos

英語でCommitを書こう
https://speakerdeck.com/pwim/ying-yu-dekomitutowoshu-kou
がよかったよ by muo

コミットが主語になる
(This commit) add...
(This commit) change...

過去形がいいんじゃない派
コミットログのサマリーをとって、バージョンの change log に使えるじゃん

(This commit) added...
(This commit) changed...

進行形で書かれてることがあった、進行形はやめようよ by itog

動名詞もあると思うけどw by amedama


----

isHogeHoge() と canHogeHoge() どっちがわかりやすい？ by sobachanko

isAccessible() と canRead() とか
どっちがいいの？どっちも bool が返ってくる。

一般的な英語としてはどっちでもいいと思う。
より口語的なのは can の方。どっちを多くつかっているかによるのでは？ by nishinos

The file can read
は英語的にあり（read には読み取れるという意味の自動詞がある）
http://ejje.weblio.jp/content/read
write にも自動詞がある

英語として気持ちいいほうにするか、
既存の API に沿うか
→ プロジェクトでどっちかに統一したほうがいいのでは

File クラスとして
isReadable() と canRead() だったらどっちがいい？


---

語彙を増やす方法がしりたい by zaki

英語力を高める感じ
手っ取り早くだったら、辞書で類語をあたってみるとか

日本で書いてるとカラフル過ぎても伝わらない場合がある
computeMean() の Mean の意味を平均と受け取ってくれない（意味と理解する）ことがある by muo

Chrome のタブの機能が便利

英辞郎はたまにあやしいことがある by nishinos


---

Java のパッケージ名と配下の名前のつけ方 by fkm

何かのオブジェクトの集合体で HogeManager みたいなのを
作りたいときに Manager が曖昧なので他にいい名前ないですかね？

HogeManager がたくさん出てくるのはよくない兆候らしいよ by zaki
(HogeHandler, HogeController とかも）

何かを管理するクラスなら Manager でもいいんじゃない？ by vvakame

Manager クラスを分解しないと別の名前にできないんじゃない？ by amedama

結論:
いろんな機能を１個のクラスに突っ込んでとりあえず HogeManager はよくない
苦し紛れなら設計を見直すべし
Manager として適切（何かを管理してる？）ならそれもいいんじゃない

データベースとかで読み書きの担当とか排他処理をするのは Manager だと思う by itog


---

登録ボタンに register て付けたいときに長くなったので省略したい
省略してはいけないところといいところはあるのか？

本当は文字を小さくするなどして省略しないほうがいい
昔の文章だと、単語のどこで区切っていいか（ - でつなげるところ）は決まっている by nishinos
辞書などでは・で区切っている by zaki

基本的には省略語を使わないほうがいい。
曜日や月の名前もどうしてもスペースが足りない時だけ省略を使う by nishinos

翻訳すると長くなる可能性がどうしてもあるので、アイコンを丁寧につくるのがいい by amedama

国際的に共通化されているアイコンが決まっている
どの程度共通認識が国際的にあるかのレベルがある by amedama

Intel のまとめがあるらしい（？） by zaki


---

自動詞と他動詞の使いかた by yanzm

moveCar() と moveToCar()

class vvakame

vvakame.moveCar()
vvakame.move(Car c)

わかめが車を動かす

vvakame.moveToCar()
vvakame.moveTo(Car c)

わかめが車のところまで移動する

clipRect()
clip()
clipTo()

go と come の使い方
I'm coming とか

run など自動詞と他動詞で意味が変わる単語もあるので要注意 by nishinos


---

sign in みたいな過去形にしにくい単語をどうしたらいいのか by mainyaa

幹になるほうの単語を過去形にするのが一般的
signed in とか by nishinos

一語になってる場合は辞書をみよう！

結論：辞書は友達


---

Android でレイアウトのID名に悩む @itog

結論: XML にコメント書こう！


---

命名の妥協点 by leibun

C言語を書いてます
関数名を決めるのに時間かかってしまう
みんなどこで妥協してるの？

名前と設計は別個に考えられないのでは？ by itog
インターナル（public と private の private）なら簡単に決めていいんじゃない？ by muo


---

メソッド名に引数名を含ませたい場合前置詞や接続詞ってどうしたらいいの？ @corosuke

どの前置詞が自然かというのは、辞書や Google で検索してどういうのが多いのか調べるのかいい by nishinos


---

会場を提供してくれた TOPGATE さんありがとう！
ピザを注文してくれたけいご君ありがとう！