個人開発の手順
個人でソフトウェアの開発を始める際の手順について整理していきます
1. はじめに
注意: ここではあくまでɯ̹t͡ɕʲiが個人開発をやっていく際の手順について整理します。そのため、一般的な開発の手引書として参考にできるかは不明です。
個人開発は、
「自分の生活のここに問題があるから解決するツールが欲しい」「誰かが困ってるらしいから直してあげたい」「社会の問題を解決して貢献したい(イキリたい)」といった問題解決型欲求
「(特定の技術・サービス)を試してみたい」「あのツールを(特定の言語)で再実装してみたい」といった個人的興味型欲求
のどちらかによってスタートすることが多く、どちらの欲求によって開始するかで技術選定の基準が大きく異なるため、それぞれのパターンについて手順を記載している箇所があります。あるはずです。
どちらのパターンについても、成果物はソフトウェア及びドキュメントになるはずなので、2章、3章では成果物の保存・公開の手順と、ドキュメントの作成方法・執筆規約について記載していきます。
ソフトウェア(プログラム)はコンピュータに対し、プログラミング言語によって作業手順を指示し、結果を得るものであるため、4章では言語と周辺ツールの選択について記載していきます。また、5章ではその言語と周辺ツールの学習方法・選定方法についても記載していきます。
ソフトウェア(プログラム)は、ある入力に対して、その入力に応じた処理を実行し、結果を出力するものであるため、6章、7章ではソフトウェアが入力を受け付ける方法と、ソフトウェアが出力した結果を得る方法について記載していきます。
2. リポジトリについて
2.1. 保存先
成果物の保存先として、下記を使用します。
インターネットに広く公開しても構わないものについてはGitHubにパブリックリポジトリとして、そうではないものはGitLabにプライベートリポジトリとして保存先を作成し、成果物を記録していきます。
GitHubに無料で無制限にプライベートリポジトリを作成できるようになったため、成果物はすべてGitHubに記録していきます。
2.2. ライセンス
成果物のライセンスは、下記の通り選択します。
サンドボックスや学習用リポジトリはWTFPL(つまりフリーライセンス) 言語のライブラリやその言語特化のツールについては、その言語の標準的なライセンス
2.3. リポジトリの命名規則
リポジトリ名は-区切りとする
言語・フレームワークのハローワールドは hello-(言語,フレームワーク名)
特定の技術・ミドルウェア等の試験は sandbox-(ソフトウェア名)
素振りリポジトリもこれにする
素振りリポジトリが多くなったらc18t-sandbox組織を作ってそっちに移動するかも
言語のライブラリやその言語特化のツールは (言語タグ)-(ライブラリ,ツールの名前空間またはソフトウェア名)
elixir: elixir-
golang: go-
nim: nim-
node: node-
perl5: p5-
perl6: p6-
サービス、ツールのリポジトリは (サービス名)
ウェブサービスにはweb-(サービス名)をつける
サービス、ツールのクライアントを作る場合は (サービス名-client)
クライアントに名前をつける場合は (ソフトウェア名) でいい
ドキュメント専用リポジトリを作成する場合は (ソフトウェア名)-document
(?:sandbox-)?(?:web-)?(?:サービス名|言語タグ-名前空間|ソフトウェア名)(?:-client)?(?:-document)?くらいの組み合わせはOK
2.4. リポジトリの作成手順
GitHub
1. WebからNew Repo
2. リポジトリ名と概要を入力、ライセンスを選択
3. Create
4. ターミナルから ghq get (ssh url)
git initしてhub createでもいいかもしれませんが、WebのUIでライセンスと.gitignoreを選択したいのと、GitLabと手順が変わってしまうので、ブラウザでWebから操作します。
GitLab
1. New Project
2. Visibility Lebel -> Private
3. Create
4. ターミナルから ghq get (ssh url)
3. ドキュメントについて
3.1. ツールと保存先
ドキュメントはリポジトリの/docフォルダに GitBookプロジェクトとして作成します。{2019-10-14追記}: gitbook-cliの更新が止まって久しいので、AsciiDocに移行することを検討する。 ドキュメントの独立の機運が高まった場合には、ドキュメント専用プロジェクトを用意してそちらに移行します。
どのような状況になったら移行させるかは検討中。目安として、
サービスがサーバ・クライアントなどの複数のリポジトリに分かれた時
ドキュメントを独自に公開したくなった時（独立したウェブページにするとか、pdfを配布するとか）
Asciidoctorを選択した理由
導入しやすい (gem install -g asciidoctor asciidoctor-pdf asciidoctor-diagramするだけ)
Markdownに比べ、表現力が豊か
SVGを直書きできたり、YouTubeのビデオを貼れたり、数式が書けたりする
図も直接書ける(-r asciidoctor-diagram オプションを付けて実行)
変数使える
CSSでデザインいじれる
GitBookを選択した辞めた理由
gitbook-cliの更新が止まったため(今後、GitBookはクラウドサービスとして提供される)
Markdownの表現力に限界を感じたため
導入しやすい (npm install -g gitbook-cliとCaribreをインストールするだけ)
プラグインが充実
ヘッダ・フッタいじれる。HTML、PDF出力のデザインをCSSで変更可能(これさえできればなんとでもなる感)
Sphinxを選択しなかった理由
動作する環境を準備するのが割と大変
reStructuredTextを覚えるのが厳しい
Markdownにも出来るけどその準備も大変
PDF 出力も大変
Re:VIEWを選択しなかった理由
あの記法を覚えないといけないならLaTeXでもいいのではと思ってしまった
LaTeXを選択しなかった理由
セットアップが大変
Markdownじゃないと文章を書けないくらいには楽な方に慣れてしまった
3.2. 作成手順
事前準備
Mac
$ brew cask install calibre
Windows
$ scoop install calibre
プロジェクト開始時
1. yarn init
2. yarn add -D gitbook-cli
3. yarn gitbook init ./doc; touch ./doc/book.json
code:book.json
{
"title": "My Book",
"description": "Book's description.",
"author": "Author",
"language": "ja",
"pdf": {
"pageNumbers": true,
"fontSize": 14,
"fontFamily": "Meiryo",
"paperSize": "a4",
"margin": {
"top": 20,
"bottom": 20,
"left": 30,
"right": 30
}
},
"plugins": [
"numbered-headings-for-web-and-books",
"uml",
"katex"
],
"pluginsConfig": {
"autocover": {
"font": {
"size": null,
"family": "Meiryo",
"color": "#FFF"
},
"size": {
"w": 1800,
"h": 2360
},
"background": {
"color": "#09F"
}
}
}
}
プラグインどうするかは検討中…基本の設定をgistに貼って利用できるようにしたい
4. project.jsonを編集
code:project.json
"scripts": {
"doc:install": "gitbook install ./doc",
"doc": "gitbook serve ./doc --open",
"pdf": "gitbook pdf ./doc ./doc/book.pdf"
}
5. mkdir -p ./doc/styles; touch ./doc/styles/pdf.css
code:pdf.css
/*
body {
background: no-repeat right -20px bottom 0px / 75% url('../confidential.png');
}
*/
.page .section.toc h1:before {
display: none;
}
.page .section.toc ol a:before {
display: inline;
content: counter(toc) ". ";
padding-right: 5px;
counter-increment: toc;
}
.page .section.toc ol {
counter-reset: toc;
}
6. yarn doc:install
TODO:
HTML, PDFの表示を調整する
3.3. 執筆規約
記述はMarkdownで行う
表現力に限界を感じたらAscii-Docに移行することも検討する
見出し要素は章、節、項を意識し見出し4まで。見出し4以下はなるべく使わない。見出し5,6が出てきたら文書構成を再検討する。
順序なしリストは-で書き始める。
*は日本語/英字キーボードで位置が違うためつらい…
式はMath記法$$で囲む。inline math記法もOK
コードは \`\`\`で囲んで必ず言語を指定
図はDOT言語かplantuml言語で記述する
なるべくこれで行きたいけど、思ったとおりの図が出ないときはdraw.ioで描くかも… 4. 開発ツールについて
4.1. 共通ツール
ghq
Gitプロジェクトを一元管理するツール。プロジェクトフォルダにずらっとプロジェクトが並んで便利
hub
GitHub操作ツール。fork使うことが多いので利用頻度は低いけどCUIから操作したいとき用
fork
Git GUI。WinとMac両対応なので素敵
pre-commit
コミット前にステージングしたファイルに対して指定の処理を通してくれるgit hookのフレームワーク。git clone したら pre-commit install しとくとよい
品質維持のための方針としては、エディタで編集時にフォーマッタやリンターにかけて事前に怪しいコードを把握、pre-commitでコミット前にリンターにかけることで、におうコードをコミットしないようにする
yarn
node.jsパッケージマネージャ。フロントエンド開発用に
asciidoctor
AsciiDocコマンドライン。ドキュメントを作成する用
vscode
基本のエディタ。主にこれで開発する
onivim
Vimをやりたいとき用。最近触ってない
git-secret
ファイルをGitに上げたいけど内容は知られたくないときに暗号化する用
filezilla
FTPツール。WinとMacがあるので採用
{2020-01-18追記} 検討の結果、WindowsはWinSCP、macOSはFinderのサーバに接続で行うことにした
macでSFTPするときは、sshfsでマウントしてFinderでファイル操作、パーミッションの変更はターミナルで行う
fish
シェル
neofetch
どの端末につないでるかわからなくなったら neofetch する、という運用
4.2. 言語ごとのツール
bash
bat
c#
Visual Studio
コード メトリックス値の測定
プレミアムにしろってうるさいので使い方考える必要がある
StyleCop/StyleCop: Analyzes C# source code to enforce a set of style and consistency rules aspnet/Extensions: .NET APIs for commonly used programming patterns and utilities, such as dependency injection, logging, and configuration css
stylus + vscode + chromeのCSSカバレッジツール
もうちょいアレしたい
stylint
fish
fortran
pFunit: Unit testing framework for Fortran with MPI extensions ruby依存のFRUITよりこっちのがいいかな
elixir
mix format
Phoenix: A productive web framework that does not compromise speed and maintainability rrrene/credo: A static code analysis tool for the Elixir language with a focus on code consistency and teaching golang
go mod: Go dependency management tool spf13/cobra: A Commander for modern Go CLI interactions GoDoc: GoDoc hosts documentation for Go packages java
JavaDoc
javascript
JSDoc
ESLint
webpack
chrome
Jest
Selenium WebDriver
Puppeteer
kotolin
nim
nimble
docopt
perl5
perl6
そんなに数ないし欲しくなったら探す
php
Composer
Laravel
phpDocumentor
powershell
python
anaconda
pip
hhatto/autopep8: A tool that automatically formats Python code to conform to the PEP 8 style guide. PyCQA/flake8: flake8 is a python tool that glues together pep8, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code. docstring + sphinx
ruby
gem
Ruby on Rails
swift
Jazzy
typescript
TSLint
ESLintに統合された
vimscript
Kuniwak/vint: Fast and Highly Extensible Vim script Language Lint implemented in Python. 4.3. ターゲットごとのツール
Windows環境構築
WSL + Ubuntu + Ansible
macOS環境構築
homebrew + Ansible
Linux環境構築
Ansible
Androidアプリ
Android Studio
JavaDoc
lint
iOSアプリ
Xcode
Windowsアプリ
Visual Studio 2019
.Net Framework 4.7.2
.Net Core 3.0
Windows10 SDK
Xamarin
Windows Template Studio
macOSアプリ
Visual Studio 2019 for Mac
Xamarin
5. 言語・プラットフォーム学習について
5.1. 共通ツール
5.2. 言語ごとのツール
bash
bat
c#
css
fish
fortran
elixir
golang
java
javascript
kotolin
nim
perl5
perl6
php
powershell
python
ruby
swift
typescript
vimscript
5.3. ターゲットごとのツール
Web
Windowsアプリ
Xamarin
6. データアクセスについて
コンソール
CLIライブラリを使って高機能なツールを作ったりする
ソケット通信
機材との通信
IRC
趣味
HTTP
Webアプリ
WebSocket
リアルタイム通信
くらいはやったことある
7. データストアについて
IIS
MySQL
PostgreSQL
Oracle
SQLite
Redis
----
コピペ用
言語
bash
bat
c#
css
fish
fortran
elixir
golang
java
javascript
kotolin
nim
perl5
perl6
php
powershell
python
ruby
swift
typescript
vimscript
ターゲット
Windows環境構築
macOS環境構築
Linux環境構築
IIS
Apache
nginx
CGI
Androidアプリ
iOSアプリ
Windowsアプリ
FirefoxOSアプリ
Webアプリ
AWS
GCP
Azure
ゲーム開発
WebVR
PICマイコン
Arduino