プログラミング

【初心者向け】コメントの有効活用

こんにちは、チズチズです。

ココ最近は、百人一首練習ソフトの開発ばかりしています。

その中では、沢山のエラーが出てきます。エラーを修正するためにはコードをしっかり理解していなければいけません。

コメントを使え!

コードを書いているうちは頭の中でこれはこうとかは理解していますが、1日経って修正しようと思ったらこの変数って何のためにあったんだっけ…等わからずに、数十分コードを1から読み直すことがあります。(数日前の出来事

面倒だと思ってコメントを書いていないと後で後悔します。

段々コード数も増えてきたら、管理も大変になってきて変数名や関数を忘れて何がどう動いているか忘れることがあります。

振り返ったときにすぐ理解できるようにコメントしましょう(推奨

変数、関数、クラスを宣言したときには何の為なのかをコメントする

コメントの鉄則

コメントなんて#付けたり”””で囲んでおけば、組み込めます。しかし、バラバラの規則でコメントしていると読みづらくなります。

下手にスペース空いたり隙間が小さいと、読みづらくなります。

最初のコメントはスッキリして見えます(基本はこれ

わかりやすいサイト

https://note.nkmk.me/python-comment/ 基本的なコメント

https://www.python.ambitious-engineer.com/archives/935  Sphinxのコメント

https://qiita.com/simonritchie/items/49e0813508cad4876b5a#%E5%BC%95%E6%95%B0%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9

NumpyスタイルのSphinx(説明がわかいりやすい

1行の中にコメントする場合の鉄則!

  •  コードから2つ半角スペースを入れてから#
  • #から1つ半角スペースを入れてコメント

 

この2つができれば完璧です。

コードの後ろにコメントするときはこれを覚えておいてくださいね!

行のはじめからコメントするときは!

  • 1文字目から#
  • #から1つ半角スペースを入れてコメント

 

#からのブランクは行中のと同じです。

関数のコメント

アメリカ人が書いたコードに関数宣言したあとにわかりやすいコメントが書かれていました。

調べてみると、どうやらSphinxスタイルのコメントらしいです。

:param 引数

:return  戻り値

関数では主にこの2つです。

大抵は

:param int : 〇〇○

のようにオブジェクトの型を書きます。

引数がない場合、戻り値がない場合は省略可能です。

簡単な例を作ってみました。 定価はint型、税はfloat型。戻り値は表示価格。

理解しやすいコメントになっています。

気を付けるべき点

  • コメントの単語は少なくして、ただの文章にしない

コメントって多いとコードを読むときに時間が取られてしまいます。

コメントは最小限の文字でたくさんの情報を詰め込む(出来る限り

読みやすく、書きやすいコードになれば最高です。

  • 読みやすく!

変数が多くなった時に数十行「何々に使う変数」ばかり書いていても読みづらく、疲れます。

例えば目的ごとに変数を分けて1行ブランクを空けてコメントと変数を記載してみたり

目的をコメントしてみたり… 自分も人にも読みやすいコメントにしましょう。(自分のコードにはあまり自信は無い…

  • コメントに必死にならない

大事なのはコードを書く作業やエラー処理等です。良いコメントを探し続けて1時間とかかかっていたら作業効率は確実に落ちています。迷ったら直感で書いてみてください。

後から良いコメントを思いついたり、記載しておきたいものがあったらそのとき書き足せばいいだけで最初の1回で完璧にしようと思わないでくださいw

模範には遠いかも知れないけど…

自分で書いてみたコードを載せます。

関数のところ、クラス前や変数のところに色々工夫(自己流)を施してみました。アドバイス欲しいのでコメント下さい。(Twitterでも…

ちなみに、このコードまだ開発途中のプログラムです。

いつかこれについても記事書きます。

ランキング機能を搭載させるつもりです。今はこれをexe化させて配布させようと試みていましたが、全然出来ませんでした。(分かる人Twitterでお願いします マジで

COMMENT

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です