先日初めてコードレビューをしていただけました。 その際コメントの書き方についての指摘が多かったので、指摘事項を備忘録としてまとめておきたいと思います。 はじめに コメントを書く際の注意点については「プログラマが知るべき97のこと」にも掲載されています。 ・コメントについてのコメント ・コードに書けないことのみをコメントにする 私はこのエッセイをレビューしていただいたコードを書き始める前に読んでいましたし、内容は頭の片隅に入っていたので、多少意識してコメントを書いていたつもりでした。 しかし、いざ指摘を受けると、エッセイで紹介されているような駄目なコメントばかり書いてしまっていました。。 書いている最中は「これは必要なコメントだろう」と思って書いていたのですが、いざレビューを受けると、そのコメントのほとんどが「全く必要のない、むしろ邪魔にすら感じるコメント」になってしまっていたのです。 私の書いたコメントは「コードに書けないことのみをコメントにする」にもあった、「ノイズ」になっていました。 どこがいけなかったのか？ 結論的には、コメントのほとんどが「自分のために書いたコメント」になっていました。 基本的に、自分の書いたコードやコメントを読むのは自分以外の他の誰かです（数週間後の自分かもしれませんが） 他の人が見てわかりやすいようなコメントを書かなければいけません。 そして、他の人が見て不要だなと感じるようなコメントは書かないようにしなければいけません。 私の場合、実装が少し複雑になった部分には、数週間後に見返しても何をしているかがすぐに分かるように 「受け取った値を～し、hogeと結合して～、fooに～して渡す」 のようにして、長文で２行にもなるコメントを書いていました。 これは自分のためのコメントです。 そもそもコードを見て、何をしているのか考え込まなければいけないようなコードは改善しなければいけません。実際そのコードはコメントをつけなくても理解できる、すっきりとしたコードにできました。 私のようにプログラミングの経験が浅い初心者は、分かりやすく、丁寧なコメントを書こうと心がけます。 少しでも「理解しずらいかな？」と思ったコードにはコメントを書きがちです。 自分の学習用のコードならコメントをどれだけ書いても良いですが、上級者からすれば、コードを見れば理解できるような事をコメントで書かれると、うっとうしく感じると思います。 さらに、そのコメントの内容が間違っている可能性だってあります。 余計に混乱させてしまうことになり、それこそノイズになってしまうのです。 Docコメントの書き方 PHPDocについても指摘された点がありました。 コードを修正し、変数名の変更があった箇所のコメントを訂正し忘れていたり、例外処理があるのに@throws句を書き忘れていたり、引数の説明に動詞（〜を受け取る。などの動詞はいらない）を書いていたりと、、、 コメントが間違っていたり、コメントに無駄な説明があったりすると、むしろコメントが無い方がマシという状態になってしまうので コメントの内容に誤りがないか？冗長になっていないか？書き漏れはないか？ 細かい部分にも注意して書かなければいけません。 VSCodeのようなIDEで、PHPの組み込み関数を使う時、関数名にカーソルを持って行くとPHPDocが表示されます。 そこで引数の型や使い方を確認しますが、とても簡潔に書かれていて、その関数を使うために本当に必要な情報だけが書かれています。 urlをクリックして日本語のページを見てもそうで、関数の用途が簡潔に書かれています。 余計な情報が無いので、すぐに理解できて使えます。 私は自分の書いたPHPDocを見直して、同じように簡潔に書けていなかったので、改めて見直して不必要だと感じた部分は削除しました。 本当に必要な情報のみを残してあとは切り捨てるだけで、すっきりとしたコメントになり、文字数も減り、内容が頭にすんなりと入ってくるようになりました。 まとめ コメントはできるだけ簡潔に、コードに書けないことのみを書く！！ コメントを通常のコードとまったく同じように考えて扱うことが重要になってきます。すべてのコメントを読む人にとって価値のあるものにし、そうでないものは即座に削除するか書き直すべきであるということです。 コードに「書いていないこと」ではなく、コードに「書けないこと」のみをコメントにするのです。
概要 本記事は、PHPフレームワークLaravel入門 第2版で学習している中の疑問・つまづきの備忘録です。 今回はLaravelからDBへの接続エラーの原因と解決策についてまとめます。 なお、PHPフレームワークLaravel入門 第2版ではSQLiteを利用していますが、MySQLに読み替えて同じことを行なっています。 発生したエラー peopleテーブルのレコードを全件検索しようとした際に、下記のエラーが発生しました。 ソースコード HelloController.php /////////一部抜粋 use Illuminate\Support\Facades\DB; class HelloController extends Controller { public function index(Request $request) { $items = DB::select('select * from people'); ////ここでエラー発生 return view('hello.index', ['items' => $items,]); } PHPフレームワークLaravel入門 第2版 原因 .envに設定していたDB_HOSTが誤っていました。 #.env DB_CONNECTION=mysql DB_HOST=127.0.0.1 #######ここが原因 DB_PORT=3306 DB_DATABASE=laravel_practice DB_USERNAME=sail DB_PASSWORD=password なぜDB_HOST=127.0.0.1ではだめだったのか 127.0.0.1は、自分自身を指す特別なIPアドレスです。ここではLaravelが動いているホスト自身を指します。 しかしMySQLが動いているのは別のホストであり、そちらを指定してやる必要がありました。 MySQLのホストを調べるには、docker psコマンドを使用します。 出力結果のNAMESを確認すると、別コンテナで動いていることがわかります。 $ docker ps ////出力結果は一部抜粋 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 286f413a566c sail-8.1/app "start-container" 8 days ago Up 8 days 0.0.0.0:80->80/tcp, 8000/tcp laravel-practice_laravel.test_1 77c6251fe186 mysql/mysql-server:8.0 "/entrypoint.sh mysq…" 8 days ago Up 8 days (healthy) 0.0.0.0:3306->3306/tcp, 33060-33061/tcp laravel-practice_mysql_1 解決策 .envに設定していたDB_HOSTを修正します。 #.env DB_CONNECTION=mysql DB_HOST=laravel-practice_mysql_1 #######ここをMySQLが動くコンテナ名に修正 DB_PORT=3306 DB_DATABASE=laravel_practice DB_USERNAME=sail DB_PASSWORD=password ちなみに、DB_HOST=mysqlに設定することでも接続可能です。 コンテナを起動したら、アプリケーションの.envファイル内のDB_HOST環境変数をmysqlに設定することで、アプリケーション内のMySQLインスタンスに接続できます。 Laravel 8.x Laravel Sail 参考文献 PHPフレームワークLaravel入門 第2版 Laravel 8.x Laravel Sail
PHP8.1にバージョンアップしpeclでインストールを行おうとした際に発生した問題です．解決方法まで書いていきます． 基本情報 $ cat /etc/os-release NAME="Ubuntu" VERSION="20.04.3 LTS (Focal Fossa)" ID=ubuntu ID_LIKE=debian PRETTY_NAME="Ubuntu 20.04.3 LTS" VERSION_ID="20.04" $ php -v PHP 8.1.1 (cli) (built: Dec 31 2021 07:26:20) (NTS) Copyright (c) The PHP Group Zend Engine v4.1.1, Copyright (c) Zend Technologies with Zend OPcache v8.1.1, Copyright (c), by Zend Technologies 問題 MongoDBとの接続のためPHPのドライバーを入れる際に発生しました $ sudo pecl install mongodb PHP Warning: foreach() argument must be of type array|object, null given in /usr/share/php/PEAR/Command.php on line 249 XML Extension not found a~~~~! XML拡張機能が見つからないのね 解決 ということでXML拡張機能をインストールします $ sudo apt-get install php-xml php8.1-xml 最後に問題のあったコードを再度実行します $ sudo pecl install mongodb WARNING: channel "pecl.php.net" has updated its protocols, use "pecl channel-update pecl.php.net" to update downloading mongodb-1.12.0.tgz ... Starting to download mongodb-1.12.0.tgz (1,392,375 bytes) ...................................................................................................................................................................................................................................................................................done: 1,392,375 bytes 633 source files, building 問題なく実行できたのでOKです
