これまで携わったプロジェクトでソースコードを納品することはあまりなかったのですが、いざ求められるとどうするかなーとふと思ったので真面目に考えてみました。
前提
題材にちょうどよさそうなPHP（Web）で考えます。
納品先の対象はWebシステム開発を行う企業で、二次受け（自分）が元請にソースコードを納品するという流れを想定します。ありがちな話です。
設計書やテストには触れず、ソースコードにフォーカスします。
コードのドキュメント（APIリファレンス）
PHPにはphpDocumentorというツールが大変便利です。
Slim FrameworkのスケルトンプロジェクトをそのままphpDocumentorにかけてみました。
いかにもAPIリファレンスっぽくて良い感じの雰囲気が出てます。
実は上記の元のPHPファイルにはPHPDocが1行もありません。PHP7以降に実装されたプロパティの型定義やnullableを使っていれば@varや@returnはなくても良いようです。
これは既存プロジェクトにも導入しやすく嬉しいポイントです。
PHPDocは他にも色々あるので幾つか記述してもう一度phpDocumentorにかけてみました。
↑class上部に@authorや@description、@copyrightを追加した結果です。
↑@deprecatedのメソッドはこんな感じに。
アーキテクチャ
設計や保守の観点からもこれが最も重要だと思ってます。
PHPでまだ名前空間を使う文化がなかった頃（PHP5.3〜5.5系）は独自の階層を作ってrequire/includeで他のファイルを読み込むといったフルスクラッチが主流だったので、その頃と比べるとだいぶ良くなった感はあります。
近年感じる問題としてはFWのデフォルトの階層／機能をそのまま使うことで無秩序なコードが量産されがち、という点です。トランザクションはどこで行うのか？ビジネスロジックはどこに書くか？例外の扱いに関するポリシーは？といった決め事が無く、開発者によって色んな実装を見かけることがあります。
少しネガティブな言い方をしましたが、常に何となくMVCで出来ている、という割り切った目線で見るとそれほど悲観的ではないのかもしれません。
ツールはPlantUMLやマーメイド記法のようなテキストベースで表現できるものがGit管理できて好みです。バイナリベースだとGoogleスプレッドシートのようにオンライン編集がないと昨今の便利ツール群に淘汰されそうですね。
こちらは実装より前に作るのが望ましいですが、遅くともリリースしてしまう前にアップデートする習慣を作った方が長生きしやすいです。（経験談）
環境構築資料
環境が１つではない場合、例えばローカル環境とクラウド環境があるならそれぞれの違いを明確に記入します。具体的には環境変数、php.iniやWebサーバ（NginxやApache）の設定値、ミドルウェアの情報。
特にLaravelだとメールやストレージ、セッションといったミドルウェアの部分が綺麗に抽象化されているため、設定値を変えるだけで切り替えが出来てしまいます。そのためローカルとクラウドで異なる部分を見落とさないようにしましょう。
たまに自分のPC固有の絶対パスや自社のプライベートIPをハードコーディングするのを見かけます。
解決方法には相対パスを使ったりローカル環境で自身を指すときは127.0.0.1を使う、といったアプローチがありますが、難しい場合は自分の環境のみに適用される設定ファイルを用意して.gitignoreに追記するといった方法もあります。
あと、PHP自体にはビルドという概念はありませんがDockerを利用している場合はコンテナ周りの情報も必要です。Dockerfile、docker-composeなど。
zip納品の場合はvendorディレクトリを含むかどうか少し悩むかもしれませんが、私的には不要だと思います。セットアップ方法の箇所に補足しておくのが吉。
それ以外の本来、gitでは管理しないようなキャッシュやログ、個人の設定ファイルは忘れずに削除しましょう。納品作業が複数回起こることを見越して簡単なシェルスクリプト書きたくなりますね。
納品資料
ソースコードと前述の図だけだとあまり親切な印象は持たないかもしれません。
エンジニア同士のやりとりであればzipで固めて最低限のものを渡すだけで疎通が取れるかもしれませんが、こういう所でボロが出ないように気をつけたいところです。
そこで個人的に「納品資料」を添付することを推します。一般的に使われる「納品書」とは異なります。
納品資料はWordのようなドキュメントファイルにプロジェクトの簡単な概要や前述のアーキテクチャ図、ソースコードからドキュメントを生成する方法を記載します。
昨今のPHP／JavaScript開発ではCIやLint、テスト、ビルド周りの設定ファイルが沢山使われることもあるため、プロジェクトルート直下のファイル／ディレクトリの説明なんかもあるとより親切です。
デザインに明るい方に体裁を丸ごと依頼できれば最高です。
表紙にプロジェクト名、企業ロゴ、担当者名などを記載し、ページ全体のテーマカラーを当該システムのプライマリーカラーにしたりします。
細かいですがWordはPDFに変換します。
以上、自分が外部の人に納品するならこうするかな、という話でした。
社内の引き継ぎだと現実的に厳しい(´･_･`)
