tomo toomuat

技術文書の書き方

このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。

科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。

しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の役に立つのではないかと考えて記します。

Top HN posts

WGSL 3D SDF Primitives

Revision: 06.08.2023, https://compute.toys/view/407

Sphere - exact

fn sdSphere(p: vec3f, r: f32) -> f32 {
  return length(p) - r;
}

Neco関連リンク

Necoとは

Necoとはいったい何なのか。

Some thoughts on building software

Lately I have been busy reading some new books on Domain Driven Design (DDD) and software architecture -- including a short yet eye-opening one in Python and a great one in F#. At the same time, it seems that more people in the Functional Programming world are looking at more formal approaches to modelling -- some examples here. This has brought some thought from the background of my brain about how we should model, organize, and architect software using the lessons we've learnt from functional programming.

Before moving on, let me be clear about this being just a dump of some thoughts, not always well-defined, definite

おことわり

既に他媒体のインタビューなどで発表済みの内容をモンタージュしたものであり、卜部のことを詳細にストーキングしている読者がいるとすれば新規のコンテンツを含まない。
卜部の人生は卜部の人生なのであっておまえらの人生ではない。「所謂普通の人生」を送ってきたという認識は寸毫もない。性急な一般化は危険と言わざるを得ない。

何個か前の受託開発の会社をやめたきっかけの話

当時、その案件にはひとりアサインで、客先常駐であった。幸いにして常駐先の皆さんには本当に良くしていただいて、困りごともなく、業務も適量で、掛け値なしによい客先だなと思っていた。

しかしそうなってくると、所属先に所属している意味ってなんだっけという疑問がむくむくと頭をもたげてくるのである。客先常駐ひとりアサインというのは客先常駐ひとりアサインであるがゆえに、会社がこんだけ抜いてるぞというのが隠しようがないわけ。客先に請求書持っていくのも自分なんだから単価も分かるし、振り込まれてる給料も分かる(明細見れば社保の会社負担分とかも分かる)。俺が所属先に投げてるバックオフィス業務は、この抜かれてる金額に見合っているか?

ところが。ところがなのである。やめるぞと宣言して常駐が解除になり、所属先に残りのしばらく通っていると、いろいろなことが見えてくるのだ。たとえば所属先の同僚と何気なく会話する。たとえばバックオフィスの人達と(やめるから)書類のやりとりをする。たとえば所属先の営業が電話をかけている。そういうごく些細なことの積み重ねがあるのだ。会社は、中抜きするだけの謎の組織ではなかった。もっとディティールがある。そこを無視して、というか、そこが不可視化されて、金のやりとりだけ見えてしまうから、不要という話に傾いてしまったんだと気づいた。まあ言った以上はそのままやめたし次も良かったから後悔もないけど、不幸な、というか、回避策は何かあったんではないか。

	#!/usr/bin/env -S bash -c "docker run -p 8080:8080 -it --rm \$(docker build --progress plain -f \$0 . 2>&1 \| tee /dev/stderr \| grep -oP 'sha256:[0-9a-f]*')"

	# syntax = docker/dockerfile:1.4.0

	FROM node:20

	WORKDIR /root

	RUN npm install sqlite3

	linters-settings: # 設定のデフォルト値は、https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml で確認できる
	depguard: # packagesに宣言されているモジュールの取り扱いに関するルール。ブラックリスト形式で使っているので、列挙したものを使うとエラーになる。
	list-type: blacklist
	packages:
	- golang.org/x/xerrors # go 1.13で必要な機能はすべてerrorsに取り込まれたので使わない
	- github.com/rs/zerolog # ログ出力用のライブラリはプロジェクト内部に作ったファクトリ関数経由で使うため
	packages-with-error-message:
	- golang.org/x/xerrors: "エラー処理は標準のerrorsを使って下さい。スタックトレースが必要な場合のみpkg/errorsを使って下さい"
	- github.com/rs/zerolog: "ログ出力は example.com/myproject/logger#Newから利用して下さい"
	dupl: # コードのコピペを検出するルール。閾値のトークン数を越えるものをエラーにする

	#!/usr/bin/awk -f

	# This program is a copy of guff, a plot device. https://github.com/silentbicycle/guff
	# My copy here is written in awk instead of C, has no compelling benefit.
	# Public domain. @thingskatedid

	# Run as awk -v x=xyz ... or env variables for stuff?
	# Assumptions: the data is evenly spaced along the x-axis

	# TODO: moving average