00:04
8月21日日曜日です。
9時18分です。
おはようございます。
本日も朝活を始めていきたいと思います。
昨晩、実は大阪に来ていました。
今、新大阪のホテルで朝活をやっております。
大学の友人と飲むために、
わざわざ大阪に来たという感じです。
そのせいで仕事に影響を及ぼしてしまったというところ、
大変に申し訳ないなと思います。
タイトルはあれとおりですけど、
Technical Writing for Developersという記事の続きから、
読んでいきたいと思います。
前回、一昨日、読んでいて、
3分の1ぐらいまでだったので、
今日、読み切れるかわからないですけど、
頑張っていきたいと思います。
では早速いきたいと思います。
無職ヤメトロさんとシチュエーションさんと
けいさんとよなぎさんですね。
おはようございます。ご参加いただきありがとうございます。
では早速読んでいきたいなと思います。
今日はLighting Code Commentsというところから
書いていきたいなと思います。
コードコメントの書き方ですね。
他の開発者のために書くものは、
コードに何を書くか、コードをどう説明するか、
仕事全体の品質に大きな影響を与えることがあります。
興味深いことに、どのプログラミング言語にも、
コメントを書くための標準的な機能が備わっています。
コードが何をしているのかを説明するものなければなりません。
というのは、このような曖昧なコメントがありません。
というので、一応2つ
コメントの例が載っていますけども、
例えばRedという変数があって、
それにAsterイコール1.2ですね。
1.2倍をしてそこに代入するというやつですけども、
そのコメントに、
Multiply Red by 1.2 and reassign itと書いていますけども、
こういうコメントは意味がないと。
一目瞭然ですし、やったことが目に見えていますので、
そこは意味がないよねと。
同じように、RedのAsterイコール1.2、
かけ算して代入するというコメントとして、
Apply a reddish effect to the imageと書いています。
こうすると結局、
何を意味するのかというか、
何をする構図なのかということのコメントがちゃんとわかっていますので、
分かりやすくていいなと思います。
何をするかじゃなくて、なぜなのかというところですね。
大切なのは文脈ですと。
自分はどんなプログラムを作っているのかというのは、
まさに自分自身で問いかけるべき質問なのですというところでした。
これは僕もいろんなコメントを書いてきたんですけども、
一番嬉しいコメントってその意図ですよね。
理由とかなぜそれを書いたという意図を書いてもらうと、
嬉しいのかなというふうに思ったりします。
それをしないと結局、
正義になったりしがちで、
03:01
誰も触らないみたいな行動のコメントになってしまうので、
この辺は注意したいなというところでした。
次々いきますね。
続いて、Comment should add valueというところですね。
コメントというのは価値を与えるものだけではならないと
おっしゃってますね、この方。
何が良いコードコメントなのかを見る前に、
怠惰なコメントの例というのを2つ紹介してみましょう。
さっそくコード2つ出てきているので、
ちょっと見ていきましょうかね。
ソースコードなので音読になって申し訳ないですけど、
const age="32",というコード。
まずコードが書いてあって、
コードコメントが、
initialize age="32",と書いてます。
これも確かに分かりやすいというか、
結局意味がないですよね。
何をしているのか、とりあえず初期化という付加情報は入っているので、
なるほどと言われますけど、
constで定義しているんだから、それは初期化でしょというのが分かりますよね。
あとこれはCSSのコメントですね。
CSSで、
blur="32px",というCSSがあって、
それに対してのコメントが、
creator blur effect with 32px radius
って書いてますね。
これもそうですね。
意味はそのまんまですよね。
32pxのブラーを作ってますよというだけに過ぎない。
そういうエフェクトを付けているだけに過ぎないよね。
というコメントです。
これについての著作ですけど、
このコメントの目的は、コードの一部に価値を与えることで、
それを繰り返すことのないことを忘れないでください。
それができないなら、コードをそのままにしておこうが良いでしょう。
むしろこれを読ます人間の時間と頭を使うことになってしまうので、
特に意味のないコメントになってしまうんですよね。
これらの例がタイダなのは、
コードが明らかに行っていることを
ただ単にもう一回記述に過ぎないからです。
この場合コメントは冗長で、
私たちはすでに知っていることを伝えていないすぎず、
付加価値を与えていませんので、
こういうのがタイダなコメントということですね。
ではでは、どういうコメントが良いのかというと、
コメントは現在のコードを反映するだけで、
古いコメントというのは大規模なプロジェクトでは珍しいことではないですね。
プログラマーであり、一緒にいて、
いわゆるクールな男とか、
デイビッドを想像してみましょう。
デイビッドは文字列のリストをAからZまで
アルファベット順に並べたいと思い、
JavaScriptで当たり前のことをしてみます。
ソースコードを見てみると、
citiesイコールソートワーズというメソッドですね。
独自カスタムメソッドだと思うけど、
ソートワーズ括弧のcitiesというふうに書いています。
要はソートワーズという関数があって、
citiesという変数を入れてソートしているんですね。
それをもう一回citiesに入れています。
06:01
そういうコードがあって、これに対してのコメントが
ソートシティーズフロムA to Zって書いてますね。
本当にこれも無意味なコメントだなって感じですけど、
デイビッドはソートワーズが実際には
ZからAAのリストをソートしていることに気づきましたが、
出力を逆にすればよいので実は問題はありません。
さっきのcitiesイコールソートワーズ括弧
シティーズという関数の実行した後に
citiesイコールリバース括弧シティーズ
というふうにコードを書いてますね。
確かにそれは意味はそうなんだけど、
無駄なことをやってますね。
残念ながらデイビッドはコードのコメントを更新しませんでした。
さて私がこの話をせず、あなたが見たのは
上のコードだけだったと想像してください。
2行目のコードを実行した後、
シティーズというのはZからAAを
ソートされると当然思うでしょう。
この混乱騒動というのは古くなったコメントが原因だったというのもありますね。
これは大げさな例かもしれませんが、
締め切りに追われていて、
同じようなコードが起こることが起こる可能性があります。
そしてこれはよくあることですね。
ありがたいことにこれはある簡単なルールに従うことができます。
コードを変更したら同時にコメントも変更するという
一つのルールだけでいいということです。
このシンプルなルールはあなたとあなたのチームを
多くの技術的不採から作ってくれるでしょう。
ちなみに技術的不採にも別のリンクが張られていて、
別の記事が書かれています。
これも後ほど興味がある方は見てみてください。
さて、お粗末なコメントがどのようなものか分かったところで、
良い例をいくつか見てみましょう。
はい。
良いコメントとお粗末なコメントは見たので、
続いて見ていくんですけど、
非イディオマティックなコードを説明すべきだというのがコメントだと言っています。
時には自然なやり方が正しくないことがあります。
プログラマーは標準を少し破る必要があるかもしれませんが、
そのときはその根拠を説明するコメントを
少し残しておくとよいでしょう。
はい。
コードがちょっと続くのであれですけど、
今回はファンクションのaddSetEntry
という関数を定義してあって、
引数にsetとvalueという2つの引数を取っています。
setは多分objectなのかな。
set.addという関数があるらしくて、
それにvalueの値を入れていて、
そのaddしたものを最後にreturnでsetを返している感じですね。
はい。
コメントがソースコードの中にあるんですけど、
don't return set.add because it's not
chainable in IE11って書いてますね。
IE11じゃ動かないよということをとりあえずコメントします。
はい。
これに対してこれは便利ですよと言ってますね。
もしあなたがこのコードをレビューする責任者であったならば、
何が問題なのかを説明するコメントがそこになければ
09:01
修正したくなったかもしれませんね。
結局問題はIE11で動かないということが書いてあるので、
これは別に僕は悪くないと思いましたけどね。
ただ、don't returnなのでIE11のときにどうするのという
別の問題は発生するなと思いましたけど。
はい。
続いてcomments can identify future tasksですね。
コメントで今後の課題を明確にしましょうというところです。
はい。
コメントでもう一つ有効なのはもっとやるべきことがあると認めることだというところですね。
よくあるコメントではto doとかありますね。
今回はto doコロン
use a more efficient algorithmって書いてますね。
より効果的なとか素晴らしいアルゴリズムがあるはずなんで
それを使えみたいなふうに書いてますね。
これはですね。
こうすることで自分の流れというか
自分のタスクに集中することができます。
そして後日あなたもしくは他の人が戻ってきて修正することもできます。
個人的には
なんでこのアルゴリズムじゃダメなのかとか
エフィシェントアルゴリズムというふうに書いている理由とかまで
書いてくれたほうが僕はいいんじゃないかと思いました。
じゃなければ別に変えなくていいんじゃないのという意見も出てくる気はするので
ここは僕あんまりいいコメントとは思わなかったですね。
はい。
続いていきましょう。
続いてcomments can link
リンクバックかto the sourceですね。
リンクすることができますと言っています。
例えばスタックオーバーフローであなたの問題を解決する方法を探してみたら
見つかったとしましょうと。
そのコードをコピーペーストした後に将来参照するために
あなたを助けた回答ですね。
へのリンクを保持することは時々いいことだと言っています。
すなわちそのコードのコメントに参照したとか
もしくは参考にした
スタックオーバーフローのリンクそのものもコメントに書いておくということですね。
これはよくやることです。とてもいいことだと思いますね。
これはその代わりソリューションが変化する可能性があるため
重要なことと言っています。
万が一コードが壊れてしまったときのためにコードがどこから来たのかを知っておくのが
常に良いことだと言っていますね。
これはもう大賛成ですのでぜひぜひ書いてくださいという感じですね。
別にスタックオーバーフローじゃなくてKiitaでもいいですし
GitHubの移住でもいいですけど
あくまで参考にしたコードなんですよというのがあるのであれば
ぜひぜひ書いてくださいですね。
今のが一応コメント回りのセクションでした。
続いて
Writing Pull Requestsですね。
Pull Requestsの書き方についてのコメントです。
コメントじゃないわ。技術を入りたいと思いますね。
Pull Requestsの書き方ですが、Pull Requestsとは
どんなプロジェクトでも基本的な側面だと言っていますね。
コードレビューの中心に位置するものです。
このような表現がなければすぐにチームのパフォーマンスのボトルネックになってしまいます。
これはもうそうですね。
12:02
良いPull Requestsの説明には
どのような変更がなされるのか、なぜそれが良いと
なぜそれがなされるのかがまとめられています。
大規模なプロジェクトでは実際の例から引用した
一つの例というのがプロジェクトのテンプレートがありますよと。
例えばですけど例が書いてあって
H2ですね。
4つぐらい書いてあって
一つ目がProposed Changesですね。
変更の提案をしますというディスクリプションを
バーッと書いていますね。
次にTypes of Changesで何が変更されましたかというのを書いています。
それを過剰書きで書いていますね。
さらにチェックボックス式ですね。
これマークダウンだけどチェックボックス式の
リストで書かれているような。
最後にチェックリストです。
どういう風に貢献したのかとか
あとは何をしたのかとか
リントとかテストとかしっかり通ったのか
みたいなチェック項目ですね。
その辺は皆さんのプロジェクトで決めてくださいと思います。
あと必要であればちゃんとドキュメンテーション更新しましたが
みたいなチェックリストがあります。
最後4つ目です。Further Commentsですね。
例えばこういう1つのテンプレートがありますよというところですね。
というのを使うことで
このプロリクエストの意図と理由と
いろんな安全性とかなんちゃらという保証をしてますよね
というのを使うのはいいことかなという風に決めました。
続いてAvoid Value PR Titlesですね。
曖昧なPRタイトルで
プロリクエストのタイトルは避けてくださいよということでした。
例えば以下のようなタイトルは避けてくださいと。
AvoidとかFix、BugとかAdd Patchとかですね。
このタイトルは本当に
怒りそうです。
僕が出されたら普通に怒ります。
これ多分
Gitのコミットメッセージでもこんなの出してきたら怒ると思います。
極論なんて
プレフィックスでFixがついていれば別に分かるよって。
あとそのBuildなのかBugなのかというのも
何を変えたとか何をしたのかというのをちゃんとタイトルを書いてほしいですよ。
すみません、余談でした。
戻ります。
これらのタイトルは我々が使っているBuild、Bug、Patchが何であるかを説明をとさえしていません。
Buildのどの部分が修正されたのか
このBugが突破されたのか
どのPatchが追加されたかといったちょっとした詳細があれば
同僚との良いコミュニケーションとコラボレーションを確立するのに
コミュニケーションとコラボレーションを確立するのに
長い道のりを歩むことができます。
レベル設定をしてみんなで同じページに集めるんです。
プールリクエストのタイトルというのは
典当的に命令形で書かれます。
これはプールリクエスト全体を一行で要約したもので
プールリクエストによって何が行われるのかを説明するものです。
だから命令形になるのは仕方ないねというところです。
15:01
以下というのが一つの例ですよと言っていますね。
3つぐらい書いていますね。
2つ目が
3つ目が
みたいな感じでタイトルを書いてもらえるといいんじゃないかと
いうところでしたね。
何たらかんたらでカスタムソースセット属性を
サポートするみたいなタイトルだったり
デフォルトの画像設定を70%の画質に変更しましたみたいな
プールリクエストだったり
全ての組み込みに対して明示的なセレクターを追加するとか
そんな感じのタイトルであればいいんじゃないかと
言っていますね。
プールリクエストタイトルって結構バカにならないですよね。
もちろん中身を詳細開いてみないと
ただタイトルにはせめてそういうものがあってほしいなと思いますね。
本当に重大なものだったり
すぐにレビューしなきゃいけなかったり
緊急とか高いプールリクエストだったりする可能性もあるんですけど
GitHubのプールリクエストだったらタグがあるので
HotFixタグとか付けたりとか
セキュリティーインシデントのFixFMみたいなのを付けることもある。
そういうタグを付けてカテゴライズするっていうのが
一つの方法ではあるんですけど
ノーのリソース食うので
タイトルの方でバンと書いてあるのが一番わかりやすいなと思ったりしますね。
アボイドロングPR
長いPRは避けましょうと
大きいPRって感じかな
大きなPRっていうのは膨大な記述を意味し
誰も何百何千行ものコードをレビューしたくはないでしょうし
逆化されてしまうかもしれません
何千行のプールリクエストなんて普通にリジェクトします
物によりますけど
その代わり次の方法があります
大体4つぐらいあります
1つ目がチームと一周でコミュニケーションをしましょう
2つ目はちゃんとプランニングをしましょう
3つ目が問題をより小さな断片に分解していきましょう
それぞれの問題をプールリクエストして別々に作業していきましょう
これ全部アグリというか
ぜひやってくれって感じですね
最後2つが一番大きくてですね
より小さく分解して
みんなで別々作業するってのが大事ですよね
作業は分担してマルチスレッドで動かす方が明らかに早いですから
もちろんコンフリクトする可能性もあったりするので
そのファイルの扱いには注意ですけど
その分はコミュニケーションが必要だというところがありますね
ということでよりすっきりしたんじゃないかというところですね
例えばレガシーなシステムを
大規模にガッとフルリプレイスしたりする案件によっては
18:00
フレームワークのバージョンがだいぶ古かったりするので
それをガッと上げるときに
破壊的に変更が結構多かったりするので
プールリクエストが長くなるのは仕方ないと思います
あとは同じような規律が
至る所にバーッとあって
いっぺんにまとめて変更するみたいなのもあったりすると思います
そういうものは
長いかもしれないですけど
1個1個のコードの変更自体がたった1行だったりするのが
何十ファイルに分かれているのであれば結構分かりやすくていいので
そういうのは除外というか例外として
別にいいんじゃないかというのもありますけど
ただデカい変更をするというのは
チームメンバーとメンバーほとんどみんなに影響するので
レビューし合うというのも1つもいいかもしれないし
レビューする内容も分担できるのであれば
メンバーで分担してレビューするのもいいかもしれないですね
そういうのは応募にしてできない可能性は多いにありますけど
でもやっぱりいかにせよ
デカいプールリクエストは基本的には避けましょうという感じです
やっぱり小さく分けて
数が多い方が1個1個のフレックスをパッパワッパ
レビューし終えるので
その時間を1時間も2時間も奪うよりは全然いいなと思います
続いて
Provide details in the pull request bodyですね
プールリクエストの本文にちゃんと詳細を記載しましょう
これはでもさっきのプールリクエストのテンプレートがちゃんとチーム内にあるとか
GitHubを使っているんだったらその.githubの下に
プールリクエストテンプレートというファイルを作って
そこでちゃんとテンプレートが作られているのであれば
プールリクエストを作るときに自動でそのテンプレートを読み込んで
作ってくれるのでそれでいいんじゃないかと思います
じゃあ戻ります
プールリクエストのタイトルとは異なり
本文は以下のような詳細を記載する場所ですよというふうにこの人は言っています
なぜそのプールリクエストを行いますか
なぜこの方法がベストなんでしょうか
そのアプローチの欠点と可能であればそれを解決するためのアイディアです
最後にバグやチケットの番号とかベンチマークの結果など
というのを書いてください
あとイシュー使っているとかジラとか
バックログとか使っているのだったら
そのタスク管理のタスクチケットのリンクも書いておくの結構いいなと思います
もしくはタイトルにそういうチケットの番号と
変更した内容とか書くのもいいかもしれないですね
この辺は運用はチームによっていろんなやり方があると思いますけど
以上これでした
以上今のがPRの話ですね
続いてまだまだいきます
レポーティングバグなので今イシューの話ですね
バグレポートというのは
どんなプロジェクトでも最も重要な側面の一つです
そしてそのすべての優れたプロジェクトというのは
ユーザーからのフィードバックによって成り立っています
通常数えきれないほどのテストを行った後でも
ほとんどのバグを発見するのはだいたいユーザーなんですよと言っています
これはそうですよね
僕らがどれだけテストしたらバグもないだろうと出しても
21:02
結果ユーザーから出てくるということがほとんどですし
逆にユーザーじゃないと見えないバグなのでたくさんありますからね
またユーザーは偉大な理想主義者であり
時には機能のアイディアを持っていることもあるので
そのアイディアについてもぜひ耳を傾けてくださいと
技術的なプロジェクトではこれらのことを全て
課題を報告することで行われます
一周立てることでそういうことができていますと
よく書かれた課題というのは他の開発者が見つけやすくまた対応しやすいものになります
例えばほとんどの大きなプロジェクトには
テンプレートが不足していますよと
これもいわゆるイシューテンプレートというやつですね
イシューテンプレートもちょうどこの記事内でリンクが貼ってあるので
この辺も見てみてくださいということでした
angular-translateと言っていますので
angularの方式サイトの翻訳周りのところのリポジトリかな
だと思いますね
そこにちゃんとイシューテンプレートがあって
割と良さそうだなと思いましたけど
一応コードもマークダウンで書いてあるので
ちょっと音読ですけど読んでいきたいと思います
今回はシャープ3つなのでヘッディング3ですね
5つぐらいの項目に分けられているそうです
一つ目はsubject of the issueですね
issueの主題は何ですかと
続いて二つ目はyour environmentなので君の環境は何ですかと
例えば今回はangular-translateなので
angular-translateのライブラリーのバージョンはとか
あとはversion of angularだからangularそのもののバージョンはとか
あとどのブラウザーを使ってますかとか
そのブラウザーのバージョンは何ですかとか
いわゆる環境ですね周りのことを書いてくださいと
三つ目にstep to reproduceですね
要は再現手順を書いてくださいとかですね
四つ目はexpected to the behaviorなので期待する動作ということですね
正常形なんですかというのを書いてくださいと
次ですねactual behaviorなので
実際にどういうことが起こっているんですかというのをちゃんと書いてくださいと
この順番はちょっと僕は前後したくなりましたけど
一旦この辺のことを全部issueに書いてくださいねっていうのが
このangular-translateっていうリポジトリの
issueテンプレートでしたこんなことを書いてくださいと
いうところですね
あとgather screenshotsって書いてますけど
スクリーンショットを本当に収集しましょうっていう風なところですね
お使いのシステムのスクリーンシューティングユーティリティを使用して
問題をキャプチャーしてくださいと言ってます
しかもわざわざシステムスクリーンショット
シューティングユーティリティっていうところに別のリンクが張ってあるので
take a screenshot.orgっていうサイトがあるのでそこを見てみてくださいと
一応サンプルとしてそういうのもあるよと言ってます
スクリーンショットユーティリティためだけのツールがあるんですね
続いてCLIプログラムのスクリーンショットの場合は
テキストが明確であることを確認しましょうと
UIプログラムの場合はスクリーンショットが正しい要素や状態を
キャプチャーしていることを確認しましょう
問題を実証するために実際のインタラクションをキャプチャーする必要もあったりします
24:00
その場合はもちろん画面収録ツールを使って
GIFの顔を作ってくださいっていう感じですね
動画的にキャプチャーをとってくださいと
本当そういう感じですね
もちろんこのGIFですね
スクリーンレコーディングツールというところにまたリンクがありますね
これまたメイキングGIFっていう
GIFを作るページのリンクが載ってますので
その辺も見てみてくださいということでした
続いて
How to reproduce the problemですね
問題の再現性ですね
再現方法についてですけど
プログラマーにとってバグが自分のコンピューター上で再現されると
解決するのがずっと簡単になります
そのために良いコミットメッセージには問題を正確に再現するために
手順が含まれていなければなりません
コミットメッセージに含まれていなければならない
なるほど
これはちょっと新しいですね
コミットメッセージの中に含めるんですね
僕はここちょっとあんまり同感はなかったですね
それは別にプロジェクトの中に書けばよくないか
もしくはプロジェクトの補足説明とか
その辺の中に含めるのがいいんじゃないかなと思ったりはしました
ちょっとここは
そういう例もあるかなということでした
ただ再現手順を書くのはもちろん大事なのでそこはマストですね
続いていきましょう
Suggestは構図ですね 原因を考えましょうということですけど
バグを発見したあなたならなぜそのバグが発生したのか
考えられる原因を提案できるかもしれません
特定のイベントが発生したときだけバグが発生するとか
モバイルでしか発生しないとかそういうのを書けるかもしれません
またコードベースを調査し何か問題を表しているかを
特定するのは悪くないでしょうと
そうすればあなたのイシューはより早く解決され関連する
プレイエクスにアサインされる可能性もありますというところでした
こういうようなイシューを立ててくださいねというところですね
イシューを立てられるのはだいたい
エンドユーザーじゃなくてエンジニアだったりはしますけど
見つかったらバリバリ書いてくださいということですね
もちろんエンドユーザーの人に書いてもらえるのは一番いいんですけど
それは厳しいと思うのでエンドユーザーがコメントをできるような
もっと皆さんが慣れているようなところで
アクセスできるコメントを投げる場所みたいなのがあると
もっといいのかもしれないですね
今のが一応あとイシューの話でした
続け出すとか
もうちょっと続きますね
えーとですが
今だいたい26分7分くらい読んだんですけど
やっぱり残り時間で読むとしたらあと
余裕で10分くらいオーバーしそうなので
これはですねまたここで区切らせていただいて
また明日の朝ですね
読んでいきたいかなと思います
明日は多分これ読んでたら全部は読んで
27:01
時間が若干余ると思うのでまた別の短い記事見つけようと思っておりますので
また興味があればごゆるりと参加いただければなと思います
では今日の朝活はこちらで一旦終了にしたいかなと思います
日曜日の朝9時ちょっとからご参加いただき
大変にありがとうございます
皆さん本当朝勤勉だなというところですごいと思いますね
では日曜日ゆるりとお休みいただいて
お休みいただいてまた明日から1週間頑張っていけたらなと思いますので
そんな感じです
では終了しますお疲れ様でした
