良いソフトウェアを書く方法

最終更新日：2024-11-22 | ページの編集

概要

質問

他の人が使えるソフトウェアをどのように書けばよいですか？

目的

R を書く際のベストプラクティスを説明し、それぞれの正当性を説明する。

プロジェクトフォルダを構造化する

プロジェクトフォルダは、コードファイル、マニュアル、データ、バイナリ、出力プロットなどのサブフォルダを作成して、構造化され、整理された状態を保つようにしましょう。
これは完全に手動で行うことも、RStudio の New Project 機能や、ProjectTemplate のような専用パッケージを利用することも可能です。

ヒント: ProjectTemplate - 可能な解決策

プロジェクトの管理を自動化する方法の一つとして、サードパーティパッケージ ProjectTemplate をインストールすることがあります。
このパッケージはプロジェクト管理のための理想的なディレクトリ構造を設定します。
分析パイプラインやワークフローを整理し、構造化するのに非常に便利です。
RStudio の標準プロジェクト機能や Git と組み合わせることで、自分の作業を追跡し、共同作業者と簡単に共有できるようになります。

ProjectTemplate をインストールします。
ライブラリを読み込みます。
プロジェクトを初期化します。

R

install.packages("ProjectTemplate")
library("ProjectTemplate")
create.project("../my_project_2", merge.strategy = "allow.non.conflict")

ProjectTemplate とその機能に関する詳細は、公式ホームページ ProjectTemplate を参照してください。

コードを読みやすくする

コードを書く際に最も重要なのは、それを読みやすく、理解しやすくすることです。
他の誰かがコードを見て、それが何をしているか理解できるようにする必要があります。
多くの場合、この「他の誰か」とは、6 ヶ月後の自分自身であり、そのときに過去の自分に腹を立てている可能性があります。

ドキュメント: 「どのように」ではなく、「何を」「なぜ」を伝える

最初は、コマンドが何をするかを説明するコメントを書くことが多いでしょう。
それは、自分自身が学んでいる最中で、概念を明確にしたり、後で思い出す助けになるからです。
しかし、このようなコメントは、後になってコードがどの問題を解決しようとしているのかを思い出せない場合には、あまり役に立ちません。
なぜ問題を解決しようとしているのか、そして何の問題なのかを説明するコメントを含めるようにしてください。
どのように はその後で良いです。それは実装の詳細であり、理想的には気にする必要がないものです。

コードをモジュール化する

おすすめの方法は、関数を分析スクリプトから分離し、別のファイルに保存することです。
プロジェクト内で R セッションを開くときにそのファイルを source します。
このアプローチは、分析スクリプトをすっきりさせるだけでなく、便利な関数のリポジトリを作成することができ、プロジェクト内のどの分析スクリプトにも簡単にロードできます。
また、関連する関数を簡単にグループ化することも可能です。

問題を小さな部分に分解する

問題解決や関数作成は、最初は難しく感じられ、コードの経験不足と切り離しにくいことがあります。
問題を消化しやすい部分に分解し、実装の詳細は後回しにしましょう。
問題をどんどん小さな関数に分解し、コードで解決できるレベルに達するまで続けてください。そしてそこから組み立て直しましょう。

コードが正しく動作していることを確認する

関数をテストすることを忘れないでください！

同じことを繰り返さない

関数はプロジェクト内での簡単な再利用を可能にします。
プロジェクト全体に似たようなコード行が繰り返されている場合、それらは関数にまとめる候補になります。

計算が一連の関数を通じて実行される場合、プロジェクトはよりモジュール化され、変更が容易になります。
特に、特定の入力が常に特定の出力を生成する場合には有効です。

スタイルを忘れずに

コードには一貫したスタイルを適用しましょう。

まとめ

プロジェクトフォルダを構造化し、整理整頓を保つ。
「何を」「なぜ」を文書化し、「どのように」は後回しにする。
プログラムを短く、単一目的の関数に分解する。
再実行可能なテストを書く。
同じことを繰り返さない。
命名規則、インデント、その他のスタイルの側面で一貫性を保つ。