howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。

はじめに：この記事を書いた動機 これらの素晴らしい先行記事を見て、「言語学を用いれば、共通点を見つけ出して一般化・大項目化したり、取り違えやすいエッジケースを明確化できるんじゃないか？」と思ったことが、この記事を書き始めたきっかけになります。 １章は３つの主要なパターンとその詳細・例外、２章はそれらに関する文法的な解説になっています。 構造化・体系化が必要な理由 太郎くんと花子さんが英作文の問題を解いています。 次の日本語を英文に訳せ。 (1) 彼女は楽しい人だ。彼女といると退屈することがない。彼女はいつも新しいことに挑戦して…… 太郎くん（『楽しい』って英語で何やったっけ……） 狩井先生@ 1年6月「exciting は楽しいって意味やで～」 ~~ 月日が流れる ~~ 柱鈴先生@ 2年4月「excited は楽しいって意味やで～」 太郎くん（……って教わったけど、exciting か e

はじめに 「なんか、レビューのたびに変数名を指摘されてる気がする...」 「日本人なんだから、英語で命名とか無理...」 こんなお悩みありませんか？ この記事では、「プログラマーが英語の命名で悩んだ時にどうすれば良いか」をフローチャート形式で解説します！ これであなたも駆け出しエンジニアを卒業できるかも!? ※本記事はLaravel,Vue.jsのプロジェクトで運用されているルールを元に解説しています。 プロジェクト内だけの内輪ルールも含まれていますので、ご了承ください。 対象者 この記事は下記のような人を対象にしています。 駆け出しエンジニア プログラミング初学者 PHP(Laravel),JavaScript(Vue.js)で英語のネーミングに苦戦中 前提知識 下記のような中学・高校で学ぶ内容については理解していること前提で解説します。悪しからず。 三単現のsって何？ 5文型(SV/S

両者の違い エディタでホバーするといずれも 1 という型が表示され、一見同じことをしているように思えるかもしれません。しかし、これらは明確に違う型を持ちます。 その前に、すべての変数は、その変数の型とは別に、Type Narrowingという仕組みによって一時的に別の型として取り扱う機能があります。 それぞれ、仮に global type と narrowed type と呼ぶことにします。 すると、const n: 1 = 1 は (global type, narrowed type) = (1, 1) ですが、const n = 1 は (global type, narrowed type) = (number, 1) です。これは以下のようなコードで確認ができます。 const n: 1 = 1; const getN = () => n; // inferred as () =

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? オセロAIってなんか難しそう？そんなことはありません。むしろゲームAIを学ぶ様々なレベルの人にこれ以上ないくらい最適です。この記事ではオセロAIを作ると何が良いのかをひたすら語っていきます。そしてオセロAIをこれから作る人のために参考になりそうな記事をいっぱい貼り付けていきます。 私自身はもうかれこれ1年以上オセロAIにどっぷりハマっています。詳細は以前書いた記事で。 オセロAIをおすすめする3つの理由 1. 原始的なゲーム木探索を学べる オセロは「二人零和有限確定完全情報ゲーム」と呼ばれる種類のゲームです。この名称を説明すると、 二人

Value Objectが盛り上がっているらしい。 Value Objectについて整理しよう - Software Transactional Memo Value Objectの説明に異論がないものの、主題はValue Object Obsessionのほうですよね。 こちらも聞いてみた。 fukabori.fm よい機会なので、よくわかっているつもりの、値オブジェクトというかドメイン固有型について再考してみよう。 それは値か属性か それはエンティティの全メンバーやデータベースの全列のために「顧客郵便番号」「送付先郵便番号」「事業所郵便番号」「契約日」などのクラス(メンバではなくクラス！)を定義して、immutableな振る舞いを強制する事を以てValue Objectであると言い張り、ドメイン知識の断片をそれぞれのクラスに書き散らして「高凝集になった」「型システムが守ってくれる」と喜

Value Objectとは何であるか? マーチン・ファウラーのPatterns of Enterprise Application Architecture(PofEAA)やエヴァンス・エリックのDomain Driven Design: Tackling Complexity in the Heart of Software(DDD)が原典であるが、PofEAAではこう切り出している。 When programming, I often find it's useful to represent things as a compound. プログラミング時は物をcompound(合成物)として表現すると便利なことがしばしばある。 例えば2次元空間上での座標のように複数のメンバ(属性)を持つ物は便利である、と。しかしそれらを比較する方法は一意ではない、そこで Objects that a

技術的負債 (technical debt) は、ソフトウェア開発の用語で、手早い解決策を選択することで生じた潜在的な手直しのコストを指す。技術的盆栽 (technical bonsai) は、完成した技術を鑑賞し、また完成度の向上のために手直しを加える趣味を指す。技術的負債とは特に関係はない。定義はいま考えた。 「技術的盆栽」という言葉はここが初出ではなく、先行例が存在している（ことを Google が教えてくれた。）「文化的雪かきと技術的盆栽」というエントリで「ちょっとしたこだわりや調整にいくらでも情熱を注ぐことができる」ことが特色であると説明している。これは僕の「技術的盆栽」の解釈とも一致する。 技術的盆栽の道具のひとつとして git があり、そこでは技術的改良の履歴は木構造で管理される。それ自体もまた盆栽性があり、さまざまな枝 (branch) の形の妙などを楽しむことができる。オ

そこそこの規模があるプロジェクトで実行すべきタスクを定義するとき、初手として Makefile を使いがち。 Pros make は事実上どんな環境にもあることを期待してよい シェルで実行されるコマンドをそのまま書ける タスクの依存関係が明示できる Cons make では positional arguments が使えない 少し複雑なことをしようとすると Makefile 専用の文法を覚える必要がある 現代では、ファイルベースのタスクの依存関係は make が発明されたころほどは必要ではない Docker とか Go とか Webpack がよしなにしてくれることが多い 例: docker compose のラッパー ちょっとしたコマンドのラッパーを書きたいことがある。Makefile を書きはじめたらすべてのエントリポイントを make にしたい。ということで、以下のような Make

Web apps are a mandatory part of every modern application nowadays, no matter how small or complex it is. From one-click apps that convert pictures to Photoshop, everyone wants fast and easy access to the app, and the web is one of the easiest ways to do that. At Serokell, we use TypeScript for writing web applications. But our main programming language is Haskell. And in this article, we want to

とりあえず、よく言われてるやつから埋めていこうと思う。 構造体にライフタイムを持たせない 構造体にライフタイムを持たせるのは「基本的に」避けよ、というのが重要なのは間違いないのだけど、これをもう少し実践的な内容にしたい。ちょっと考えてみたけど、こういうのはどうだろうか。 ある関数呼び出しの中でしか絶対に使わない。returnするまでにその構造体のデータは全て破棄される。static変数に退避させることもできない。アロケーションもその関数が面倒を見る。そういう一蓮托生できる関数呼び出しに心当たりはあるか？ ある→ 構造体にライフタイムを持たせてもよい。 ない→ ライフタイム禁止。 そう考えてみると、DIとかReduxとかとも通じるところがあるかもしれない。「つべこべ言ってないで全部の責務を一番外側に持っていく」という決断ができるときは構造体ライフタイムが選択肢に入る。

There’s No Such Thing as Clean CodeのHacker Newsコメント経由でコードやシステム設計・最適化についての良いコメントを見つけた。どうやらHacker Newsで何度も引用されているらしいが日本語で言及された記事が見つからなかったので取り上げてみる。 コメントは2016年のSandi MetzのThe Wrong Abstractionに関するもので、発言者のcurun1rいわく「私は設計の優先順位をこの順序で学習することで、優れた開発者になれた」。*1 4つの基準と優先順位のガイドライン 状態 > 結合 > 複雑性 > コード量 私は状態 (state)、結合 (coupling)、複雑性 (complexity)、コード量 (code) の順に削減することでコードを最適化する。 コードがよりステートレスになるなら、結合を増やすこともいとわない 結

正規表現の"正規"って何 ある時ふと思いました。 「正規表現の"正規"って何だろう？」 「何を根拠に"正規"を名乗っているのか？」 と。 「誰かが『これが正規の表現だ』と言ったはず」で、 「それは周りにどうやって"正規"だと認められたのだろう」 ということが気になったので調べてみました。 "正規表現"という名前でなくて、"ジャックさんの表現"とか"記号ごちゃごちゃ表現"だったらこんな疑問も持たなかったのですけど。 数学における"正規"とは 一般に"正規"というと、"正規品"や"正規の手順"といったように"本物の(genuine)"や"公式な(official)"といった意味がありますが、数学の"正規"はちょっと違います。 数学で"正規"(および"正則"、英語では"regular"または"non-singular")は、ある概念に強い制限をかけたもの、という意味です。強い制限をかけたものは取

自分は Ebiten という 2D ゲームエンジン (ゲームライブラリ) を趣味で開発しています。使用しているプログラミング言語は Go です。 2013 年 6 月に最初のコミットを行ったので、現在 8 周年の 9 年目です。 Ebiten は「くまのレストラン」などのモバイル及び Nintendo Switch 向けゲームで使われており、一定の実績があります。 ゲームエンジンの開発は一朝一夕では終わりません。Unity や RPG ツクールといった既製品がある中、ゲームエンジンをわざわざ自作することは酔狂かもしれません。ではなぜそのようなことをしたのでしょうか。端的に言うと「ミニマムな API で実用的な 2D ゲームが作れるかどうか」ということを証明したかったのです。自分の美的感覚の追求です。この目的に気づいたのは割と最近のことです。やっていくうちに「自分がやりたかったのはこういうこ

概要 最近退職に伴いTypeScriptプロジェクトのCI/CDの見直しを行っているので主にプルリクに対するCIを中心に何をやっているのか(やっていた＆やろうとしているもの含む)紹介します。 それぞれはさらっとした紹介のみです。 ちなみに書いてから気づいたんですが殆どTS以外でもできます。 tsc, prettier, eslint 基本です。恐らく殆どのプロジェクトでやっているかと思います。 tscは--noEmitオプションを付けて実行、eslintは--cacheと--quietオプションを付けて実行しています。 prettierは--list-differentオプションを付けると差分があった場合(=prettierが適用されていないファイルがあった場合)にエラーにしてくれます。 CIでWebpack等でバンドルしてる場合はこの辺を明示的に行わなくてもそこでコケるのでやってないケー

こんにちは。この記事は筆者が製作した ESLint 向けプラグイン eslint-plugin-import-accessを紹介する記事です。 このプラグインにより TypeScript プログラムに擬似的なpackage-private exportの概念が生まれます。JSDoc で@packageとアノテートされたexport宣言は、そのファイルが属するディレクトリの外からインポートすることができなくなります。 従来、TypeScript で可能なカプセル化の最大の単位は「ファイル」であり、ファイルからエクスポートしない変数はそのファイル（モジュール）の中に閉じている一方で、一旦エクスポートしたものはプロジェクトのどこからでもインポート可能になります。これでは不都合な場合がありました。 最近の具体的な例としてはRecoilが挙げられます。筆者の以前の記事では、Atom や Select

Artificial LIfe ENvironment (ALIEN) is an artificial life simulation tool based on a specialized 2D particle engine in CUDA for soft bodies and fluids. Each simulated body consists of a network of particles that can be upgraded with higher-level functions, ranging from pure information processing capabilities to physical equipment (such as sensors, muscles, weapons, constructors, etc.) whose execu

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに みなさん形式手法をご存知でしょうか？ 名前くらいは聞いたことあるけどいまいち何かわからないという方が多いのではないでしょうか。 その通りです。形式手法はアカデミアではそれなりに研究されているものの、 一般の（特にWeb系）ソフトウェア開発者が携わることはなかなかないのではないかと思います。 この記事ではソフトウェア開発に形式手法が導入されないのはなぜなのかを考察します。 この記事ではアジャイルソフトウェア開発において形式手法を導入する際のハードルについて考察します。 追記 本記事について、「形式手法は流行っていない」というのは