さぁコーティングだ！ とその前にするべきこと。

質問

こんばんわ。今、私はプログラミングの勉強をしています。
いきなりですがそんな私のコーティング時の慣習を聞いてください。

私はいまから書こうとしてるプログラムの内容を
簡単な自然言語的な疑似プログラミング言語で
概要というかしようとしていることを
コメントとしてソースコード内に書き記す、ということをやっています
たとえば、PHPであれば
<?php
　 // commentにpostされた書き込みの内容を代入

　 　//接続リソース　＝　user,pass、DBに接続
　 //接続リソース（”SQLクエリー ="SLECT ○○　ここにcommentを挿入　DESC"）

　//閉じ処理（接続リソース）
1
　<hmtl>
　　　　//foreachで○○テーブルのcommentを全部出力
　</html>
?>

みたいな感じです。

プログラミングを勉強するにつれ、
コーティングする作業は、
現実を抽象化し、記号化し、コードに落としこんで演算していくことだと実感しています。
その抽象化の過程で自然言語での解説を挟むことで目的とする抽象度まで
のはしごをかけ、そこに昇りやすくする。そんな感じでやってます。

目標としてる
「どんどん頭にコードが浮かんできて入力する手のほうが追いつかない。」
....そんな水準にはほど遠い状況ですが、実際にそんなことができる人ばかりではないのでは？とも思ってます。そこでプログラマーの皆さんに質問です。
最終的なソースコードを自分の頭から放り出すまで、
それを確実なものにするために
なにか、良き習慣やら方法論などをご存知ないでしょうか？

UMLなどもその一つだと思いますが私はまさにソースコードを書いてる、
エディターを開いてるそのときにできるものを知りたいと思ってます

なにか「俺こんな思考プロセスをふんでるよ」っていうノウハウ（やそういう方法論を解いてる書籍）をご存知でしたらぜひ教えてください。
もし、それが門外不出のノウハウでなく、不特定多数に提供できる良き慣習、アイディアであればぜひとも教えていただきたく思います。

私は本気で転職を考え本気でプログラミングの勉強に励んでいます。
どうか、力をかしてください。

回答No.6

めとろいと（@naktak）

＃２です。

全然別なお話になってしまうかもしれませんが、始めたばかりでしょうから、へんなクセがつく前に
やり続けて、それが当たり前になった方がいいことを書いてみます。

・だらだらと処理を書き続けない。
　⇒とにかく見づらいです。他人が見てわかるコードにしましょう。
　　処理の責任範疇を明確にし、メソッドを分割して処理を細分化しましょう。
　　すると自然に1つ1つの処理が分かり易くなります。
　　私の1メソッドの行数はよっぽどコードを分割しづらいことを前提に最大80行までは許容しますが、
　　もっと厳しい人だと1メソッド30行までとかあります。

・色んなカテゴリに属する処理をごちゃまぜにして書かない。
　⇒責任範疇があいまいになり、処理がスパゲッティになりがちです。
　　処理が密結合になると同じような処理を何度も書いたり、バグも生み出しやすいです。
　　それを明確にする為にメソッドを使うわけですが、その結果、複数のメソッドを
　　1つのカテゴリと捉えてクラスを用いることができます。

・色んな画面でも使うのか、同一画面でも色んな場面で使うのか、1度きりの処理なのか
　⇒どの範囲で利用する処理なのかを把握した上で、最適な場所（別ファイルor同一ファイル）に
　　プログラミングします。
　　全く用がないところで定義してたせいで、他人がプログラムを修正する際に呼び出してし
　　まったら・・・？

・変なスコープ（public, protected, private）で宣言しない
　⇒なぜそのスコープが必要なのかを考えた上で、最適な位置に最適なスコープで宣言しましょう。
　　それが崩れると更にバグを生みやすくなります。
　　特に、クラスなくせにpublicメンバだらけで、外部から壊し放題とか。

・コメントを省略しない
　⇒クラス、メソッド単位のコメントは面倒でも必ず書く！変更されたなら必ずメンテナンスする！
　　プログラムを見るのは自分だけじゃない！
　　自分がそんな趣味レベルのふざけたコメントとかを見たら殺意を湧かないのか？！と考える。

他にもいろいろ、覚えたてのころから気を付けてやってクセにした方がいいものがありますが、
なんかキリがなくなってきそうなのでやめます。

結構、1画面を作ろう！となった時、画面を作る前に作るプログラム、というのがあります。
オブジェクト指向言語は画面を作る前の設計が重要であり、それが抜けていると1画面を
作るのに時間がかかったり汚くなったりします。（別にオブジェクト指向言語に限った話ではありませんが）
ここでいう設計とは、画面を作る前に作るプログラムです。

例えばDB接続をするという処理がありますが、いちいち画面ごとにプログラミングするかと
言ったら、まずしないでしょう。どう共通化しようか？と考え出します。
それを考え、作っている間は、画面は全然作ってませんが、これが重要です。

その時その時で場当たり的にやりたいことをだらだら書いてると、いつまでも綺麗なコード
にはなりません。
当たり前のようにコードするプログラムを、どうやって特定の画面に依存しないように
追い出そうかを考えます。（依存していいものは別）

お礼

個別にお返事ができず、定型文によるお礼になることをお許しください。
皆様の回答はすべて隅々まで読んでいます。
なるほど、初心者では考えつかないような思慮にとんだ内容でなんどもなんども心の中で反芻しています。
それらをプログラマーとして成長するための良きアドバイスとして受け止め、今後の学習行動に反映し、プログラマーとして良き習慣を身につけるべく日々
勉強やコーディングに励んでいこうと思います。

私がこれらの見解を自分で考えだすことは、ここで聞かなければ
ずいぶんと先のこととなったでしょう。皆様のおかげで一足飛びで（いくらか）成長できたような気がします。
本当にありがとうございました。

回答No.5

hanabutako

> 私はいまから書こうとしてるプログラムの内容を
> 簡単な自然言語的な疑似プログラミング言語で
> 概要というかしようとしていることを
> コメントとしてソースコード内に書き記す、ということをやっています

なんというか、調度よい補助輪だと思います。
プログラムの全てでこれをすると非常に効率が悪いと思いますが、自分が不慣れなところのコードを書く場合や複雑なアルゴリズムのコードを書く場合はコードを書く前に何をするか整理をして、自然言語で記述しておくのは有効でしょう。
また、その時描いたコメントを誰が読んでもわかるような形で残しておけば一見したらわからない複雑なアルゴリズムの説明書となるでしょう。

プログラミングにかぎらず、勉強し始めたことというのは一つ一つ手順を確認しながら確実に行うというところから始めて、そのうち意識しないでもほとんどができるようになると思います。その時には説明しないと理解できないような複雑な処理以外について、コメントを書く必要はなくなるでしょう。

仕事でプログラムを書く人が残しておくべきコメントというのは他の人が描いたコードから呼ばれる可能性がある関数の説明でしょうね。逆に、他の人が描いたコードから呼ばれることになっていない関数は名前空間を汚染しないよう、極力見えないようにしておきます。
ちなみに、PHPの関数などのコメントはphpDocumentorの文法で書いてみると良いかもしれません。

テスト駆動開発だと実際のコードを書く前にテストを書くのが当たり前なので、プログラムを書く前にテストを書くかもしれません。テストを書くのはあとでも良いのですが、自分のコードを客観視してコーナーケースを調べるようなテストを書くことで、格段にコードの質が上がることでしょう。特に、PHPのような動的型付け言語だと、実際のコードが期待していた型と違うデータが来たためにエラーになるようなケースは動かすまでわからないので、テストですべてのコードを一度動かしておくというのが大事だと思います。

PHPで単体テストを書くにはPHP Unitというのがあるようです。
http://phpunit.de/manual/3.6/ja/automating-tests.html

"エディターを開いてるそのときにできるもの"ということで言うと、一言で言ったら自分と同等かそれ以上の知識を持った他人がつっかえることなく読めるようにしておくということでしょうね。例えば、スタイルに従うとか、変数名・関数名を一意に意味がわかるものにするとか、極力単純なコードを書くとか、きちんとカプセル化をしてコードの影響範囲を閉じておくとか、Liskov substitution principleを満たすところでちゃんと多態性を使うとか、lintがある言語ならlint freeにしておく、...etc...とかあります。

ちなみに、PHPでのスタイルガイドはこういうのがあるみたいですね。
http://pear.php.net/manual/ja/standards.php

単純なコードというと、KISSの原則というものがあります。
http://ja.wikipedia.org/wiki/KISS%E3%81%AE%E5%8E%9F%E5%89%87

> 目標としてる
> 「どんどん頭にコードが浮かんできて入力する手のほうが追いつかない。」
> ....そんな水準にはほど遠い状況ですが、実際にそんなことができる人ばかりではないのでは？

どれくらいのプレーヤーを目指しているかわかりませんが、補助輪付きでプログラムを書くようなレベルではコーディングがやはり遅いと思います。

プログラミング言語の学習は外国語の学習と似ていると思います。
例えば、英文を読む時は初学者のうちはどれが述語でどれが主語か考えながらとっかえつっかえ読むと思います。また、一つ一つの単語について、日本語でどういう意味かを調べながら読むことでしょう。ある程度慣れてくると、自分が知っている単語が増えてきて、定型文というのが見えてきますから、そういうものについては、どれが主語かなどを探さずに文として意味を理解できるようになります。

プログラミング言語も同じで、ある程度慣れてくると、プログラムを文として理解できるようになってきます。辞書を引かなくてもそれっぽい英文を書けるように、思考過程で書く擬似コードはそのままその言語のコードになってきますから、複雑なことをする場合を除き、説明書も擬似コードも不要になります。

なんかまとまりがない感じになりましたが、知識の習得と実践のどちらも大事です。がんばってください。

お礼

個別にお返事ができず、定型文によるお礼になることをお許しください。
皆様の回答はすべて隅々まで読んでいます。
なるほど、初心者では考えつかないような思慮にとんだ内容でなんどもなんども心の中で反芻しています。
それらをプログラマーとして成長するための良きアドバイスとして受け止め、今後の学習行動に反映し、プログラマーとして良き習慣を身につけるべく日々
勉強やコーディングに励んでいこうと思います。

私がこれらの見解を自分で考えだすことは、ここで聞かなければ
ずいぶんと先のこととなったでしょう。皆様のおかげで一足飛びで（いくらか）成長できたような気がします。
本当にありがとうございました。

回答No.4

Wr5

>私がそういうことするのは、今日中にコードできなくて、でもイメージはできているからという時に
>備忘録として残します。
>今日中にできるならそんなコメントは不要ですから。

今日中ってワケではないですが、似たような感じでしょうかぇ……。

とりあえず、備忘録的にコメント書いておく。(実装開始が10分後でも)
備忘録的コメント書いている間に考慮不足だった処理とか洗い出し出来ることもありますし。
で、コーディングしていって実装が進んだら備忘録的コメントは削除していってますね。
# 実装進んで簡単な単体試験が終わったら…くらいが目安。
なので最初に書いたコメントは最後にはまず残ってない。

後から読む人(数週間後の自分も含む)が誤解しそうなところはコメント残しますが。
# あと、妙に実装に手間取ったところとか、ネットで探したサンプルを流用して手を入れたところは流用元のURLとか。
# まぁ、流用元のURLは後で見たときにページごと無くなっている可能性もあったりはしますけど…。後から参照したときそうなったら解読ですかね…。

コメントに嘘が書いてある。という状態にならないように気をつけてはいますねぇ。
他人が読んだときや後から手を入れるときに余計な面倒背負い込みたくない。ってのもありますし。
# それでも手を入れるときはコードの内容確認しますが。
作ったプログラムの保守を自分がやるとは限りませんしねぇ…。
# いつ何時事故に遭うか判りませんし、派遣契約がずっと続くとも限りませんし。

あとは…コーディングと関係ありませんがバージョン管理とかは使いますね。
# ローカルにSubversion入れてある。
「不具合修正した際に以前のコードをコメントにして残す。」というのは激しく読みづらくなるので。
# 仕事でそういうコード読むときは…けっこうキツい。

以上、＃１でも書いたけどPHPではなくC言語とC#でのハナシ。
# phpはよく判らん。

お礼

個別にお返事ができず、定型文によるお礼になることをお許しください。
皆様の回答はすべて隅々まで読んでいます。
なるほど、初心者では考えつかないような思慮にとんだ内容でなんどもなんども心の中で反芻しています。
それらをプログラマーとして成長するための良きアドバイスとして受け止め、今後の学習行動に反映し、プログラマーとして良き習慣を身につけるべく日々
勉強やコーディングに励んでいこうと思います。

私がこれらの見解を自分で考えだすことは、ここで聞かなければ
ずいぶんと先のこととなったでしょう。皆様のおかげで一足飛びで（いくらか）成長できたような気がします。
本当にありがとうございました。

回答No.3

hogehoge78

私の場合は、機能や目的ごとに、区切って考えていく方法を取ってます。

例文で考えると、先に、
・PDOをラップしたデータベース接続クラスを作る。
・HTMLとPHPのロジックを最低限分離したいので、テンプレートエンジンを使うか簡易的なものを作る。

ことを前提として考えて、
<?php

$db = DB::instance();
$comments = $db->getComments();

$view = new View('comment_page', compact('comments'));
echo $view;
?>

とか、なんとなく抽象的に書いてみて、徐々に決めていく感じです。
アウトプットに使うメソッドや関数にひと目で何をやろうというのかわかる名称を付けて、
実際に複雑に頑張る記述はそのメソッドの中に押し込めてやるといった手法です。
そしてその関数やメソッドのところでもりもりコメントを残す。

それである程度実装ができたら、使いまわす可能性を考えながら、ViewクラスやDB接続クラスを、
汎用的に使えるようにリファクタリングしてみて、次回似たような案件があったらソレを使ったり
一部を流用して、実装していくといった感じです。

でこれらを作るにあたってのノウハウや知識は、自分が使ってみて使いやすかったフレームワークだったり、
CMSなどのソースを読んだり、調べ物の副産物的に見つけた記述などを流用していってます。

お礼

個別にお返事ができず、定型文によるお礼になることをお許しください。
皆様の回答はすべて隅々まで読んでいます。
なるほど、初心者では考えつかないような思慮にとんだ内容でなんどもなんども心の中で反芻しています。
それらをプログラマーとして成長するための良きアドバイスとして受け止め、今後の学習行動に反映し、プログラマーとして良き習慣を身につけるべく日々
勉強やコーディングに励んでいこうと思います。

私がこれらの見解を自分で考えだすことは、ここで聞かなければ
ずいぶんと先のこととなったでしょう。皆様のおかげで一足飛びで（いくらか）成長できたような気がします。
本当にありがとうございました。

回答No.2

めとろいと（@naktak）

> 私はいまから書こうとしてるプログラムの内容を
> 簡単な自然言語的な疑似プログラミング言語で
> 概要というかしようとしていることを
> コメントとしてソースコード内に書き記す

そんな面倒なことしません。
コードをコメントとして書けるならば、コードを書けばいいので。

私がそういうことするのは、今日中にコードできなくて、でもイメージはできているからという時に
備忘録として残します。
今日中にできるならそんなコメントは不要ですから。

それと、質問にあるあなたの書き方よりはもっとざっくりしてますね。
当たり前というか、例えばクエリを流すなら、当然DB接続していなければならないわけですが、
当然後で自分がコードするからそれを残すわけなので、そんな当たり前のことはいちいちコメントで
残しませんし、コメントに命令文は一切書きません。
必要となる命令文を少しでも書くなら、コメントではなくコードしてしまう方が早いです。
内容も、自分さえわかればいい日本語です。

// Aとる
// comment全部だす
// あ、でもcommentの中のシングルクォーテーションだけエスケープだわ。要件的にhtmlspecialchars()はつかえん！

とかですよ。

もしくは、ほぼコードがイメージできているなら、
// TODO かいてみた
// foeach ($kvp as $key => $value) {
// echo $key . $value;
// }
みたいに、コードはあるけど未検証だよ、って状態にします。

お礼

コメントありがとうございます。
おっしゃるとおりだと思います。

なにぶん初心者、初学者ゆえ、定型文のようなお決まりのコードも
なんとなくコメントとして残しておいた。次第です。
早くこんなことをしなくてもいいような頭の中である程度完結できるスキルレベルに達したいです。

とりあえず、私の書き方にはもっと洗練する余地があることがわかり大変参考になりました。ありがとうございました

回答No.1

Wr5

>私はいまから書こうとしてるプログラムの内容を
>簡単な自然言語的な疑似プログラミング言語で
>概要というかしようとしていることを
>コメントとしてソースコード内に書き記す、ということをやっています

一応プログラマ(C。最近はC#をよく使う)ですが、私も同じようなコトしますね。

まぁ、本来であれば基本設計書とか詳細設計書とか作ってその時点で煮詰めていく…ことになるんでしょうから、コード上にそういうコメント(メモ書き)を…というのは少ないのかも知れませんが。
# 設計書求められれば私もそっちからやることになる出しょうな。仕事だし。

趣味プログラマの延長だとやっぱり、いきなりコーディング…ですかねぇ。
書面やテキストファイルなどに残らないけど、おおざっぱな設計は頭の中で済ませていたりしますかねぇ。
通勤時やヒマな時に煮詰めるとか簡易脳内デバッグとか…。

プログラマに転職しよう。というのならば、上流工程についてもいくらか触れておいた方がいいかも知れません。
IT土方のままでいるつもりなら不要かも知れませんが。

私はエロゲ会社からの転職でしたから…設計書とかは書いたこと無かったんですよね。
コードレビューなんかもしたことありませんでしたし。
自社スクリプトエンジンを開発していた部署ではやっていたっぽいですが、その部署に配属されたときにはほぼ開発終わってましたし、
ゲーム自体を作っているときには企画者とかは設計書なんてモノありませんでしたしねぇ。
コードレビューしたところで企画者やシナリオライターには宇宙語みたいな感じで理解不能でしたし。
# スクリプトレベルなんでプログラマーも割り当ては基本一人ででしたしねぇ。
# 企画者やシナリオライターの出す要求さえ満たせば実際のコードに関してかなり自由裁量でした。

お礼

コメントありがとうございます。
我流でやってみたことの方向性がある程度正しいことがわかり
安心しました。

やはり、熟練者は頭の中で設計をやってしまって直接コードを書くことがおおいのですね。

とりあえずたくさんコードを読んで、たくさん書いて、知識のストック、選択肢のストックをたくさんたくさん作り、その域にはやく近づけるよう精進します。
ありがとうございました。