SSブログ

再び聴けるKOIT [KOIT]


KOITの公式ページには、次のように米国以外では聴けないことになっています。
Streaming outside the United States:
The 96.5 KOIT App and online streaming allow you to stream in the United States. All other countries are blocked. Thank you for understanding.
しかし、過去、日本で聴けたり、聴けなかったりを繰り返しており、最近再び聴けるようになっています。

過去の記事から抜粋してKOITを紹介すると次のとおりです。
  • 米国シリコンバレーにあるPalo Alto, CAに住んでいた頃(1991年5月から1993年4月までの2年間)、カーラジオでよく聞いていたFM放送局がKOITでした。当時は、車には、カーラジオかカセットテープのプレイヤーだけしかない頃でした。KOITを聞いていると、シリコンバレーの青空や、当時はそれほど混んでいなかったフリーウェイ260を思い出します。
  • 現地の放送がそのまま流れてきますので、コマーシャルもそのまま現地の話です。
放送される曲は、1980年代から現代までとさまざまです。コマーシャルでは、シリコンバレーの地名が出てきたり、お店の名前が出てきたりします。また時々、ものすごい早口のコマーシャルが流れることがあります。

今は日本でも聴けますが、しばらくしたらまた聴けなくなるかもしれません。
コメント(0) 

伸ばすのが難しい能力(4) [プログラマー現役続行]

2003年以降のデジタル複合機のコントローラソフトウェア、2017年9月からのウェブサービスのバックエンド開発をテストファースト開発によるソフトウェアの自動テストを長年行ってきて、バックエンド開発については「WEB+DB PRESS Vol.134」の特集1「実践API設計」としてまとめました。デジタル複合機のコントローラソフトウェア開発については、過去にカンファレンスなどで話しています。

これらの長年の開発で気付いていなくて、最近気付いたことは、次の2つの活動は強く関連していることです。
  • API仕様をきちんと書く
  • そのAPI仕様に基づく、自動テストコードを作成する
ウェブサービスで、バックエンドがフロントエンドに提供するAPI仕様をきちんと書き、そのAPI仕様に基づいて自動テストコード(E2Eテスト)を作成する行為で説明したいと思います。

自動テストがない

API仕様に基づいて、そのエンドポイントを直接呼びだして行うE2Eテストコードがない場合、API仕様をどれだけきちんと書いて、修正や追加の際に更新することのモチベーションはあるでしょうか?

API仕様をきちんと書かずに開発している場合、フロントエンドの開発者は、適当に仕様を推測して試してみたり、バックエンドの開発者に(Slackなどで)問い合わせたりしながら開発を続けていることが多いでしょう。

このような開発であると、バックエンド開発者にはAPI仕様を書くというモチベーションはありません。仮に書いたとしても、長期的にきちんと保守するというモチベーションもありません。

仮に、バックエンド開発者が書いた自動テストコードがあるとしても、それがすべての機能を網羅しているのか、あるいは足りないテストがあるのかは、その開発者以外は分かりません。ひょっとしたら、その開発者も分かっていないかもしれません。

あるべき開発サイクル

記事「実践API設計」で明示的には述べていませんでしたが、バックエンドでAPIの新たなエンドポイントを追加する場合、あるべき開発サイクルは次のようになります。
  1. 新たなエンドポイントを定義して、その仕様(正常な動作だけでなく、エラーも含めて)を記述して、PR(Pull Request)のレビューをフロントエンド開発者に依頼する。フロンドエンド開発者は仕様から不明な点があれば、不明な点を明確にした内容を仕様に反映してもらうようにフィードバックする。
  2. API仕様のPRの内容をフロントエンド開発者がレビューして問題がなければ、承認する。
  3. バックエンド開発者は、API仕様に基づいて、そのエンドポイントを呼びだしてテストするE2Eテストを作成しながら、実装を行う。
  4. テストコードの作成と実装が終われば、PRを他のバックエンド開発へレビュー依頼する。
  5. レビューを依頼されたバックエンド開発者は、API仕様を確認して、E2Eテストで仕様が網羅されているか、漏れはないかを確認した後、実装をレビューして確認します。もしE2Eテストに、仕様に書かれていない動作がテストされてる場合、API仕様の更新を要求することになります。
このような開発サイクルが回っている場合、API仕様を書かないということはなくなります。ここで重要なので、API仕様に基づいて、エンドポイントを直接呼びだすE2Eテストを書けるフレームワークが整備されていることになります。

さらに、このような開発サイクルが回っている開発組織へ新たな開発者が参加しても、この開発サイクルを逸脱した開発を行うことはできません。なぜなら、API仕様や実装のPRが承認されないからです。その結果、その新たな開発者は、参加する以前の開発経験に関係なく、API仕様を書いてE2Eテストを開発することを経験することになります。

しかし、多くのソフトウェア開発組織は、そのようなE2Eテストフレームワークがないため、「自動テストがない」で述べたような状況で開発が進められてしまうことが多いと推測されます。そして、そのような開発組織でしか働いたことがない開発者は、API仕様を書くという習慣を身に付けないままとなります。
コメント(0) 

伸ばすのが難しい能力(3) [プログラマー現役続行]

伸ばすのが難しい能力(2)」の状況から、技術負債を返却して、API仕様ファースト開発への手順については、「実践API設計」で述べています。

WEB+DB PRESS Vol.134

WEB+DB PRESS Vol.134

  • 出版社/メーカー: 技術評論社
  • 発売日: 2023/04/22
  • メディア: Kindle版

記事では書いていませんが、「第5章 API仕様の技術的負債の返済」で述べている返済を実行する上での課題は、多くのソフトウェアエンジニアは、経験したことがないことなので、そのメリットを十分に理解できないことです。そのため、実際に行ってみる強い動機を持って、実践できる開発者はとても少ないと思います。

このような状況を改善にするには、私の経験からは、「やってみせるしかない」ということです。私自身がウェブサービスに本格的に従事し始めたのは、2018年6月にメルペイ社へ入社して、加盟店様向けのマイクロサービスを一から開発することを担当したときです。

「第3章 API仕様ファースト開発」で説明している手順で開発しました。その大枠の手順は、次の図(第3章の図1)で示されています(詳しいくは記事を参照してださい)。

図1 API仕様ファーストでの開発順序
03_01.png

初めてのウェブサービス開発ではありましたが、この手順が私にとっては素直な手順であり、これを実施して最初のマイクロサービスを開発しました。

その後、メルペイ内では、チームを移動していくつかのマイクロサービスの開発に従事したのですが、その多くが以下の状態でした(「第5章 API仕様の技術的負債の返済」参照)。
  • サービスのAPIに対する仕様が記述されていない
  • サービスのAPIをテストする自動テストが存在しない
単体テストは多数あっても、開発しているマイクロサービスが提供するエンドポイント(gRPCのRPCエンドポイント)を直接呼び出してテストするテストコードが存在しないという状況でした。

そのため、新たなチームへ移動するごとに「第5章 API仕様の技術的負債の返済」で述べている内容を繰り返し、一緒に開発している他の開発者にも実践してもらうように働きかけてきました。

ただし、E2Eテストフレームワークの構築は、私自身で行いました。そうやって作成したE2Eテストフレームワークは、どのマイクロサービスからも使えるように独立したライブラリとして退職前には構築しました。

このような活動の結果として、最後にいたチームでは、既存機能の修正や新規機能の追加に際しては、かならずきちんとしたAPI仕様を記述し、そのエンドポイントを呼び出すE2Eテストを作成するということを普通に行ってもらえるようになりました。

ここでの重要な点は、残念ながら「API仕様ファースト開発」はやってみせないと広がらないということです。カウシェで働き始めてから一年近くなりますが、カウシェでも今では定着しています。
コメント(0) 

伸ばすのが難しい能力(2) [プログラマー現役続行]

ウェブサービスは、フロントエンド(iOS、Android、ウェブブラウザ)とバックエンドから構成されます。バックエンドが提供する機能は、APIとして定義され、フロントエンドから呼び出されます。

この場合、「APIを定義する」行為にはいくつかのレベルが存在します。話を単純にするために、バックエンドのAPIがgRPCで定義されているとします。その場合、フロントエンドが呼び出すAPIは、protobufとして.protoファイルに定義されます。その.protoファイルに定義されるAPIにいくつかのレベルが存在します。

次は、最低限の定義のみの例です。呼び出すrpcやmessage定義が定義されているだけです。
service Greeter {
  rpc SayHello (SayHelloRequest) returns (SayHelloResponse) {}
}
message SayHelloRequest {
    string name = 1;
}
message SayHelloResponse {
    string message = 1;
}

実は、このレベルの定義だけで開発されているウェブサービスは多いと思います。その理由として以下のものが考えられます。
  • フロントエンドとバックエンドを同一のエンジニアが開発しているので、この程度で分かるから問題ないと考えてしまう。
  • フロントエンドのエンジニアからの問い合わせには、都度、Slackで回答しているから問題ない。
API仕様をきちんと記述することは開発スピードを落としてしまうので省いてしまうことが正当化されているように思われるかもしれませんが、実はそうではありません。その証しとして、サービスをローンチした後で時間的余裕が生まれてものこの状態が続くからです。

サービスを短期間で開発し、顧客に価値を提供し、サービスの価値を検証するためには、この程度の仕様で十分と考えて開発が進むと、結果的に、将来のサービスの成長を大きく阻害する技術的負債を積み上げていきます。

そもそもの原因は、「APIを定義するという行為は、この程度でよいという認識のエンジニアによって作成される」からなのです。

つまり、「伸ばすのが難しい能力」で述べた経験を積んでいないエンジニアが開発することにより、この状況は発生しているとも言えます。

続き
コメント(0) 

実践API設計:目次 [API仕様を書く]

WEB+DB PRESS Vol.134

WEB+DB PRESS Vol.134

  • 出版社/メーカー: 技術評論社
  • 発売日: 2023/04/22
  • メディア: Kindle版

特集1「実践API設計」の構成が分かるように目次を作成してみました。
第1章 優れたAPI仕様とは何か
 特集のはじめに
 APIとは
   フレームワークや標準ライブラリのAPI仕様
   企業内でのAPI仕様
 優れたAPI仕様とは
   理解が容易
   変更が容易
   テストが容易
  API仕様でよくある問題点
   API仕様が書かれていない
   エラーの記述がない
   自動テストが存在しない
  API仕様に書くべきこと
   サービスの概要の説明
   個々のエンドポイントの説明
   エラーの説明
     パラメータの不正値
     誤った順序での呼び出し
     認証と認可のエラー
     そのほかのエラー
   まとめ

第2章 gRPCにおけるAPI仕様の書き方
 gRPCとは
 API仕様をどこに書くか
 サービスの概要の記述
 個々のエンドポイント(RPC)の説明
 エラーの説明
   パラメータの不正
     InvalidArgument ── 不正なパラメータ値
     NotFound ── リソースが見つからない
     OutOfRange ── 指定された範囲のデータがない
   誤った順序での呼び出し
     FailedPrecondition ── 事前条件が成立していない
   認証や認可のエラー
     Unauthenticated ── 認証できない
     PermissionDenied ── 認可できない
   サービスの概要に書くべきそのほかのエラー
     Canceled ── キャンセルされた
     DeadlineExceeded ── 処理がタイムアウトした
     Unknown ── 不明なエラー
     Internal ── 内部エラーが発生した
   個々のエンドポイントに書くべきそのほかのエラー
     AlreadyExists ── リソースがすでに存在する
     ResourceExhaused ── サービス側のリソースの枯渇
     Aborted ── 処理が中断された
   書く必要がないエラー
     Unavailable ── サービスが動作していない
     DataLoss ── データが失われた
     Unimplemented ── まだ実装されていない
 リストオプションの説明
 まとめ

第3章 API仕様ファースト開発
 開発順序
   API仕様の記述
   E2Eテストフレームワークの検討と実装
   テストコードの作成と機能の実装
   リファクタリングとカバレッジの確認
   Pull Requestのレビュー
 不具合の修正順序
   再現テストの作成と実装の修正
   リファクタリングとカバレッジの確認
 既存のエンドポイントの修正と新たなエンドポイントの追加
 まとめ

第4章 E2Eテストフレームワークの構築
 テストフレームワークの基本的な考え方
 マイクロサービス構成でのテストフレームワーク
   書きたいテスト
     レスポンスの確認
     依存サービスを正しく呼び出しているかの確認
   E2Eテストフレームワークのプロセス
     E2Eテストのプロセス間シーケンス
   依存サービスが外部サービスの場合の解決方法
   エラーのテストは簡単
     DeadlineExceededとCanceled
     Aborted
 非マイクロサービス構成でのテストフレームワーク
 E2Eテストフレームワークの骨格
   Test Suiteプロセスの骨格
   テスト対象マイクロサービスの骨格
   フェイクマイクロサービスの骨格
   テストコードの骨格
   そのほかの考慮項目
 まとめ

第5章 API仕様の技術的負債の返済
 技術的負債とは
 API仕様の負債の返済
   既存のエンドポイントを修正するケース
     ステップ1:既存のAPI仕様の更新(見なおし)
     ステップ2:既存のAPI仕様のテストコード作成と実行
     ステップ3:新たな修正のためのAPI仕様の再修正
     ステップ4:新たな修正に対するテストコードの作成
     ステップ5:新たな修正の実装
     ステップ6:リファクタリングとカバレッジの確認
   新たなエンドポイントを追加するケース
   既存のエンドポイントの不具合を修正するケース
 返済順序のまとめ
 E2Eテストのもう一つの利点:リファクタリング
 特集のまとめ

コメント(0) 

電子版『Go言語100Tips』 [本]

8月18日に発売される『Go言語100Tips』ですが、以下の電子版も発売されます。

Kindle版

Go言語 100Tips ありがちなミスを把握し、実装を最適化する (impress top gear)

Go言語 100Tips ありがちなミスを把握し、実装を最適化する (impress top gear)

  • 出版社/メーカー: インプレス
  • 発売日: 2023/08/18
  • メディア: 単行本(ソフトカバー)

Kindle版は固定レイアウトだと思います。

PDF版

出版社のサイトからソーシャルDRM版のPDF版を購入できるようになります。
https://book.impress.co.jp/books/1122101133

コメント(0) 

実践API設計 [API仕様を書く]

WEB+DB PRESS Vol.134

WEB+DB PRESS Vol.134

  • 出版社/メーカー: 技術評論社
  • 発売日: 2023/04/22
  • メディア: Kindle版

4月に発売された「WEB+DB PRESS Vol.134」で特集1「実践API設計」を執筆していますが、そこから部分的に紹介します(目次は、こちらです)。

第1章「優れたAPI仕様とは何か --- よくある問題と記述すべき事柄」の冒頭で次のように述べています。
 今日、多くの企業がWeb サービスとしてさまざまなサービスを提供しています。Webサービスは、iOS、Android、ブラウザといったフロントエンドと、それらに対して機能を提供するバックエンドサービスから構成されます。バックエンドサービスが提供するさまざまな機能はAPI (Application Programming Interface)として定義され、フロントエンドから呼び出されます。フロントエンドは、バックエンドサービスが提供する機能を使ってユーザーへ提供する機能を実現します。
 定義されたAPI を介することで、フロントエンドとバックエンドサービスが、独立して、異なるプログラミング言語で開発できます。その結果、バックエンドサービスの開発チームは、定義されたAPI どおりにバックエンドサービスが正しく動作することを保証する責任を負います。つまり、API 定義に従って正しく動作することを、フロントエンドを接続することなく、自動テストで確認することが求められます。
 Web サービス開発の中で意外と難しいのが、バックエンドサービスのAPI を設計し、そのAPI 仕様を記述し、そしてテストファーストによるテスト駆動開発を行うことです。この特集では、それらが何を意味し、開発者にとって日々の活動で何をしなければならないかを解説します。

(太字で青にしている部分は、このブログで強調するためのものです)

長年、デジタル複合機を中心とした組込システムの開発に従事してきましたが、リコーを退職した後、2017年9月から、ウェブサービス(バックエンド)の開発に従事してきました。

当初から驚いたのが、バックエンドのサービスのAPIは定義するが、そのAPIで定義したエンドポイントを直接呼び出してサービスの機能を確認テストを書くことがほとんどないことです。つまり、さまざまなモジュールの単体テストはあるのですが、すべてを結合して一つの実行バイナリにして、APIで定義されたエンドポイントを外部から呼び出すテストコードがないことです。

この6年間で見られた問題点の多くは、「API仕様でよくある問題点」で次のように述べています。
 筆者はこれまで、Web サービス開発だけでなく、組込みシステムを含むさまざまなソフトウェア開発に従事してきました。それらの開発を通してAPI 仕様のさまざまな問題を目にしてきましたが、主なものとしては次の3つが挙げられます。
  • API仕様が書かれていない
  • エラーの記述がない
  • 自動テストが存在しない
 この結果、開発現場でよく起こるのは次のようなことです。
  • 正確な仕様は、実装コードを読まないとわからない
  • どのような場合にどのようなエラーが返ってくるかは、実装コードを読まないとわからない
  • 自動テストがないため、API がどのように振る舞うのかを簡単に知る方法がない
 これらの3つの問題をもう少し詳しく見ていきます。

記事では、これらの問題点をさらに詳しく説明しています。

ここでの問題点は、この6年間で働いてきたソラミツ、メルペイ、カウシェの3社で入社した当初に、私が目にしたバックエンドのサービス開発のほぼすべて(ただし、メルペイで私が最初に担当したマイクロサービスを除く)で目にしてきたものです。

その都度、この特集記事で述べたことを実践して改善していきました。改善は、単に私一人が行うものではなく、同じチームのメンバーが上記の問題を起こさないように開発を行ってくれるように、意識も行動も変わってくるようにするというものです。結果として、上記の問題を残さないようにする開発組織へと変わっています。

3社での経験から、おそらく多くの企業でこの問題は見られるのではないかと思っています。

関連記事:「伸ばすのが難しい能力

(2023年8月15日追記:下記は、『WEB+DB PRESS, Vol.134』のp.12より引用)

API仕様が書かれていない

 API 仕様が書かれていないというのは、次のような状況を指します。
Java などの言語で書かれている公開API を構成するクラスやメソッドに、標準のJavadoc形式があるにもかかわらず何も書かれていない。
 これを、通信方式としてGoogle が開発しているgRPCを使っているバックエンドサービスに当てはめてみます。gRPCでは.protoファイルにprotobufsと呼ばれるAPI の定義を記述しますが、そのファイルの内容が次のような状況になります。
単にサービスのエンドポイント(rpc)の定義やメッセージ構造体の定義が書かれているだけで、説明がほとんど書かれていない。

コメント(0) 

Kindle版『プログラマー”まだまだ”現役続行』 [プログラマー現役続行]

2010年9月4日に発売された『プログラマー”まだまだ”現役続行』ですが、8月1日よりKindle版がリリースされます。

プログラマー”まだまだ”現役続行 (技評SE選書)

プログラマー”まだまだ”現役続行 (技評SE選書)

  • 作者: 柴田 芳樹
  • 出版社/メーカー: 技術評論社
  • 発売日: 2010/09/04
  • メディア: 単行本(ソフトカバー)

目次は次の通りです。
第1章 ソフトウェアは「人」が作る
第2章 プログラマー現役続行
第3章 論理思考力:現役続行に必要な七つの力(1)
第4章 読みやすいコードを書く力:現役続行に必要な七つの力(2)
第5章 コンピュータサイエンスの基礎力:現役続行に必要な七つの力(3)
第6章 継続学習力:現役続行に必要な七つの力(4)
第7章 朝型力:現役続行に必要な七つの力(5)
第8章 コミュニケーション力:現役続行に必要な七つの力(6)
第9章 英語力:現役続行に必要な七つの力(7)
第10章 コードレビューのすすめ
第11章 若い人たちへ
第12章 30代,40代の人たちへ

コメント(0) 

翻訳作業終了しました:『Go言語100Tips』 [Go言語100Tips]

Go言語 100Tips ありがちなミスを把握し、実装を最適化する (impress top gear)

Go言語 100Tips ありがちなミスを把握し、実装を最適化する (impress top gear)

  • 出版社/メーカー: インプレス
  • 発売日: 2023/08/18
  • メディア: 単行本(ソフトカバー)

今回は、ギリギリまで出版社と校正作業を行い、印刷所への入稿も終わって、翻訳作業が終了しました。予定通り8月18日に発売されます。

2022年10月16日から翻訳に着手し、2023年7月24日に終わったので、約9か月を要したことになります。費やした時間は、ほぼ464時間です。途中、雑誌「WEB+DB PRESS, Vol.134」の特集記事(特集1の「実践API設計」)の執筆(85時間)が入ったので、その分、遅くなりました。

8月26日(土)(13:00〜17:00)から、一月に1回の開催で、横浜Go読書会でオンライン読書会を開催します。

https://yokohama-go-reading.connpass.com/event/284134/
コメント(0) 

Kindle版『ソフトウェア開発の名著を読む【第二版】』 [本]

出版社から連絡がなかったので、気付いていなかったのですが、『ソフトウェア開発の名著を読む【第二版】』がKindle版としてAmazonで購入できるようになりました。

ソフトウェア開発の名著を読む 【第二版】 (技評SE選書)

ソフトウェア開発の名著を読む 【第二版】 (技評SE選書)

  • 作者: 柴田 芳樹
  • 出版社/メーカー: 技術評論社
  • 発売日: 2009/10/21
  • メディア: 単行本(ソフトカバー)

紹介している書籍は、以下の通りです。
  • 『プログラミングの心理学』ジェラルド・M・ワインバーグ
  • 『人月の神話』フレデリック・P・ブルックス,Jr.
  • 『ピープルウエア』トム・デマルコ/ティモシー・リスター
  • 『デッドライン』トム・デマルコ
  • 『ソフトウェア職人気質』ピート・マクブリーン
  • 『達人プログラマー』アンドリュー・ハント/デビッド・トーマス
  • 『コードコンプリート』スティーブ・マコネル
  • 『プログラミング作法』ブライアン・W・カーニハン/ロブ・パイク
  • 『リファクタリング』マーチン・ファウラー
  • 『ビューティフルコード』ブライアン・カーニハン他

出版社に確認したところ、『プログラマー"まだまだ"現役続行』もKindle版での提供を予定しているそうです。
コメント(0)