個人開発の手順 - (/ɯ̹t͡ɕʲi/)

個人開発の手順

#dev #howistartaproject

個人でソフトウェアの開発を始める際の手順について整理していきます

1. はじめに

注意: ここではあくまでɯ̹t͡ɕʲiが個人開発をやっていく際の手順について整理します。そのため、一般的な開発の手引書として参考にできるかは不明です。

個人開発は、

「自分の生活のここに問題があるから解決するツールが欲しい」「誰かが困ってるらしいから直してあげたい」「社会の問題を解決して貢献したい(イキリたい)」といった問題解決型欲求

「(特定の技術・サービス)を試してみたい」「あのツールを(特定の言語)で再実装してみたい」といった個人的興味型欲求

のどちらかによってスタートすることが多く、どちらの欲求によって開始するかで技術選定の基準が大きく異なるため、それぞれのパターンについて手順を記載している箇所があります。あるはずです。

どちらのパターンについても、成果物はソフトウェア及びドキュメントになるはずなので、2章、3章では成果物の保存・公開の手順と、ドキュメントの作成方法・執筆規約について記載していきます。

ソフトウェア(プログラム)はコンピュータに対し、プログラミング言語によって作業手順を指示し、結果を得るものであるため、4章では言語と周辺ツールの選択について記載していきます。また、5章ではその言語と周辺ツールの学習方法・選定方法についても記載していきます。

ソフトウェア(プログラム)は、ある入力に対して、その入力に応じた処理を実行し、結果を出力するものであるため、6章、7章ではソフトウェアが入力を受け付ける方法と、ソフトウェアが出力した結果を得る方法について記載していきます。

2. リポジトリについて

2.1. 保存先

成果物の保存先として、下記を使用します。

GitHub:

GitLab:

インターネットに広く公開しても構わないものについてはGitHubにパブリックリポジトリとして、そうではないものはGitLabにプライベートリポジトリとして保存先を作成し、成果物を記録していきます。

GitHubに無料で無制限にプライベートリポジトリを作成できるようになったため、成果物はすべてGitHubに記録していきます。

2.2. ライセンス

成果物のライセンスは、下記の通り選択します。

サンドボックスや学習用リポジトリはWTFPL(つまりフリーライセンス)

言語のライブラリやその言語特化のツールについては、その言語の標準的なライセンス

例: perlなら、Artistic License

それ以外の公開リポジトリはMIT License

非公開リポジトリはCC BY-NC-ND

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の表示を調整する

デフォルトテーマのデザインを調節するときは./doc/_layoutsフォルダを作成して編集する

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でコミット前にリンターにかけることで、におうコードをコミットしないようにする

pre-commitのhookはキャッシュされるので、Windows環境とWSL環境の両方で動くようにするのは難しい。

さらに、WindowsとMac両方で動作させるには、hook自体がどちらにも対応している必要がある。そのため、両対応を考えるなら基本的にPython hookかSystem hookを選択することになる。両方で動くhookがなければ自作する

lint-staged

nodeプロジェクト向けのpre-commitツール。packege.jsonにscriptとして記述もできるし、git hookのpre-commitにもできる。両立も可。ただしgit hookのスクリプトを書き換える形でインストールするので上述のpre-commitとの両立はできない

ただし、これもpre-commitと同じく、Windows環境とWSL環境の両立、WindowsとMac両対応が難しい。package.jsonのscript、lint-stagedで呼び出すnode package、そこから呼び出されるコマンドすべてがWin/Mac両対応になっている必要があり、敷居が高い。自作してもnodeプロジェクトでしか使えないならpre-commit一本でやっていったほうがいいように思う

yarn

node.jsパッケージマネージャ。フロントエンド開発用に

asciidoctor

AsciiDocコマンドライン。ドキュメントを作成する用

vscode

基本のエディタ。主にこれで開発する

onivim

Vimをやりたいとき用。最近触ってない

git-secret

ファイルをGitに上げたいけど内容は知られたくないときに暗号化する用

sops

yaml等の設定ファイルを暗号化するツール。一部のキーのみ暗号化とかもできる。暗号化すると該当するオリジナルのデータは消しちゃってsopsコマンド経由じゃないと編集できなくなるのでけっこう怖い気がする。クラウドサービスのSecretsを暗号化するのを目的としているので、なんでもsopsで暗号化してコミットはちょっと違うのかもしれない

filezilla

FTPツール。WinとMacがあるので採用

{2019-12-30追記} Homebrewから消えてたので乗り換えを検討する必要あり Delete filezilla.rb by suschizu · Pull Request #55583 · Homebrew/homebrew-cask

{2020-01-18追記} 検討の結果、WindowsはWinSCP、macOSはFinderのサーバに接続で行うことにした

macでSFTPするときは、sshfsでマウントしてFinderでファイル操作、パーミッションの変更はターミナルで行う

fishに用意したsshfsコマンド

fish

シェル

neofetch

どの端末につないでるかわからなくなったら neofetch する、という運用

4.2. 言語ごとのツール

bash

sstephenson/bats: Bash Automated Testing System

koalaman/shellcheck: ShellCheck, a static analysis tool for shell scripts

Bash Debug for VSCode

bat

Visual Studio

コードメトリックス値の測定

GhostDoc: Painless Code Documentation

プレミアムにしろってうるさいので使い方考える必要がある

EWSoftware/SHFB: Sandcastle Help File Builder (SHFB)

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

SimenB/stylint: cli stylus linter

fish

jorgebucaran/fishtape: TAP producing test runner for fish

fish-shell/fish_indent: fish_indent - indenter and prettifier

fortran

jacobwilliams/json-fortran: A Fortran 2008 JSON API

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

quantum-elixir/quantum-core: ⌚️ Cron-like job scheduler for Elixir

bitwalker/distillery: Simplify deployments in Elixir with OTP releases!

rrrene/credo: A static code analysis tool for the Elixir language with a focus on code consistency and teaching

lpil/dogmaっていうのもある

ElixirLS for VSCode

golang

go mod: Go dependency management tool

spf13/cobra: A Commander for modern Go CLI interactions

spf13/viper: Go configuration with fangs

golang.org/x/tools/cmd/cover: Cover is a program for analyzing the coverage profiles

mattn/goveralls: Go integration for Coveralls.io

GoDoc: GoDoc hosts documentation for Go packages

Go for VSCode

java

TERASOLUNA: TERASOLUNA Server Framework for Java

JavaDoc

Debugger for Java (VSCode)

javascript

JSDoc

ESLint

webpack

chrome

Jest

Cypress: Fast, easy and reliable testing for anything that runs in a browser.

Selenium WebDriver

Puppeteer

kotolin

KDoc Kotlin/dokka

nim

nimble

docopt

perl5

skaji/cpm: fast CPAN module installer

miyagawa/Carmel: CPAN Artifact Repository Manager

tokuhirom/Minilla: Authorizing tool for CPAN modules

perl6

https://modules.perl6.org/

そんなに数ないし欲しくなったら探す

php

Composer

Laravel

phpDocumentor

PHP Debug for VSCode

powershell

python

anaconda

pip

python-poetry/poetry: Python dependency management and packaging made easy.

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

Python for VSCode

ruby

gem

Ruby on Rails

Ruby for VSCode

swift

Jazzy

realm/SwiftLint: A tool to enforce Swift style and conventions

typescript

TSLint

ESLintに統合された