どうすれば、他人が書いたプログラムを簡単に読むことができるのか？
エンジニアなら誰しも感じたことがあるのではないでしょうか。他人が書いたプログラムを全然理解できない。
自身のステップアップのために、オープンソースのコードを見て勉強を試してみるけれど、どこを見てもちんぷんかんぷん。読めない自分に嫌気が指し、エンジニアは向いていないんじゃないかと落ち込む日々もあるでしょう。
私も現在進行系で落ち込むことがあるのですが、様々な工夫を行った結果、１つの結論にたどり着いた。
それは、
エクセルでメモを取れ。
他人が書いたプログラムを正しく理解したいなら、エクセルでメモをつけよう。エクセルは至高のツールでした。なぜならば、横にも縦にも無限に感じられるくらい広がり、画面を切り取ったスクショに、図形で手軽にメモを残せるからだ。
記憶力をあてにするな、メモを取れ
他人のプログラムというのは、広大な海である。他人のプログラムを読むというのは、広大な海を船で目印もなく彷徨うことに近い。潜水艦で深く潜る感覚もあるだろう。
そうなると自分の意場所がわからなくなってしまうものだ。自分がどこから来て、どこへ行くのだろうか。それすらもわからなくなってしまう。具体的には、関数やクラス、構造体定義など気になる色々な箇所を見るイメージだ。そうなると、自分がどこを見ていたのかわからなくなってしまうので、先人たちは言った。「メモを取れ」
現代は、便利なメモツールは数え切れないほど存在する。
本記事では各ツールを詳細に説明することはしないが、代表的なものはNotionが挙げられる。
私はNotionのアンチではないが、理解するためのプログラミングメモとしては、いまひとつなのでは？と思っている。
理由はNotionが結局のところMarkdownだからだ。上から順番に記載することが求められる。
決まり切った情報を誰でも読みやすく整理するのであれば、Notionは大活躍だろう。手順書や自己紹介ページを作るようなケースなら、全く問題ない。
ただ、他人のプログラムのように、自分で考えを深めながら理解をするためのメモには適していない。なぜならば、左右方向に文章を書いていくことができないからだ。
わかりやすく言うと、関数などスクショした画像に対して図形でメモを残せないからだ。
エクセルでの作業メモを取るときの設定
私のこだわりポイントは、シートに対して以下の設定をする
- 列幅：3
- 目盛り：非表示
列幅を３にするのは、方眼紙のような見た目にするためだ。
私は階層構造を作りながら、漏れがないかを検討しています。そのときに列幅を３にしておけば、親子構造を表現するときに、1セル右にずらすだけでインデントの役割にすることができる。
この設定は、プログラミングメモを残すときには、関数のコールツリーを書きたいときにも重宝する。
呼び出し元の関数があって、呼び出し先の関数を子要素として書くことで、あとから見てもどこから何が呼び出されているのかを簡単に把握できる。
では、実際にやってみよう。
具体的なメモを実践
題材として、Pythonのopenpyxlのライブラリを見てみよう。
ライブラリの中身はこんな感じ。
では、この関数を起点にして、実際にワークブックを保存する処理を追ってこう。
def save(self, filename):
"""Save the current workbook under the given `filename`.
Use this function instead of using an `ExcelWriter`.
.. warning::
When creating your workbook using `write_only` set to True,
you will only be able to call this function once. Subsequent attempts to
modify or save the file will raise an :class:`openpyxl.shared.exc.WorkbookAlreadySaved` exception.
"""
if self.read_only:
raise TypeError("""Workbook is read-only""")
if self.write_only and not self.worksheets:
self.create_sheet()
save_workbook(self, filename)まずはエクセルを使いやすい見た目にする。
セルの列幅を3にする
セルの左上をクリックしてシート全体を選択状態にしましょう。
ホームタブにある「書式」をクリック。
「列の幅」をクリックして、3を入力する。
すると、シート全体の列幅が「３」になるので、方眼紙のように使うことができる。
「表示」タブの「枠線」のチェックを外す
方眼紙のように使いやすい見た目にするならば、枠線も消そう。
枠線が消えるので、まっさらな紙としてしようできる。
これで準備は整った。
では、ソースコードを追跡する。
プログラミングメモ
def save(self, filename):
"""Save the current workbook under the given `filename`.
Use this function instead of using an `ExcelWriter`.
.. warning::
When creating your workbook using `write_only` set to True,
you will only be able to call this function once. Subsequent attempts to
modify or save the file will raise an :class:`openpyxl.shared.exc.WorkbookAlreadySaved` exception.
"""
if self.read_only:
raise TypeError("""Workbook is read-only""")
if self.write_only and not self.worksheets:
self.create_sheet()
save_workbook(self, filename)最初のエントリーポイントがdef save(self, filename):なので、そこをトップに書こう。
複数のファイルを行き来することもあるので、ファイル名も書いておくとわかりやすいでしょう。
エントリーポイントの関数を読んでいって、目的の処理をしてそうな関数があったらトップの下に書いていく。
次は、excel.pyのsave_workbook(workbook, filename)を呼び出しいた。
名前を見る限りも、workbookを保存する関数に見える。
なので、エクセルに書く。
そのようにして、どんどん関数を深ぼってこう。
最後に目的の処理を見つけることができれば、終了である。
いわゆる、コールツリー相当のものを書くことができた。
エクセルなら、このようにスクショを乗せたり、左右にコメントを書くことだってできる。
メモを残しておくと、あとから類似の処理を調べたいと思ったときでも、見返すことでどこの処理を見るべきかを把握しやすくなる。なんて便利なんだ。
おわりに
今は他のメモを書いていませんが、処理をちゃんと書いていこうとすると左右に画像を貼ることもあるでしょう。
Markdownを否定するつもりは全くありませんが、プログラミングメモには案外とエクセルが良いのではないだろうかという提案であった。
図形をたくさん使ってメモを残したいケースもあると思うので、結構便利かなと思っている。
そして、図形を使うなら、私はエクセルが最適解ではないだろうか。
ぜひ、みなさんもエクセルを使ったメモを試してみてはいかがだろうか。
コメント