JSDocでよくね？

綾坂こと.icon

deno checkでもチェックできる

また、TypeScriptの場合型チェックが通らないとそもそもコンパイルできないため動かないが、JSDocの場合型チェックをしないまま動かしてしまうことができる

code:example.ts

function add(left: number, right: number): number {

return left + right;

}

code:example-with-tsdoc.ts

/**

* 「型についての情報が書かれている部分」と「ロジックが書かれている部分」は分離されてたほうがわかりやすいと思う

* @param left - 左項

* @param right - 右項

* @returns 和

*/

function add(left: number, right: number): number {

return left + right;

}

code:example.js

/**

* 「型についての情報が書かれている部分」と「ロジックが書かれている部分」は分離されてたほうがわかりやすいと思う

* @param {number} left - 左項

* @param {number} right - 右項

* @returns {number} - 和

*/

function add(left, right) {

return left + right;

}

一番最初に見たものから離れられてないだけじゃないかな

考えたことなかったので面白い

どういうところがわかりやすくなったと感じているのか知りたい

ただ、タイトルの「JSDocでよくね？」はsyntaxの話と、型の有用性の話が混じっている気もする

やりたければ、TypeScriptでも型だけ定義して、あとから実装に紐づけることもできる

code:ts

type Add = (left: number, right: number) => number;

const add: Add = (left, right) => left + right;

こうすれば、コードの途中に型情報は書いていない(?)

(コードってどこ？というのはある)

関数名を型名にも使わなきゃいけないのがちょっと気になるが、これは私にとって読みやすい

$ f: \R\times\R\to\R

$ f:(x,y)\mapsto x+y

実装の方ってコロンじゃなくて何だっけ

あれは実装と型を完全に別ファイルに書いているので、コードの途中に型が書かれない

近く(できれば隣)に書いてあって欲しいけど、完全に一緒に書かれていてほしくない

果たしてあれが本当にわかりやすいと言えるだろうか

TypeScriptユーザがJSDocよりもTypeScriptを好むのは

そちらの方が記述量が少ない (syntax関連)

そちらの方が表現できる幅が広い (型の有用性)

とかそういうのが大きいと思う

syntaxの方は慣れとか好みの影響が大きい思う

TypeScriptをバリバリ好んで使う人にとっては、JSDocの表現力が自分の要求に全く届いていないから使っていないだけ

JSDocで十分ならそれで良い

TSユーザが小さいプログラムにも(JSDocではなく)TSを使うのは、

単にJSDocの記法を別途覚えるのが面倒、

プログラムが大きくなったときにTSに切り替えるのが面倒

とかそんな感じではないだろうか

小さいプログラムは JS で書くから JSDoc 使わないし、大きくなったら TS 使うし

その場合、コメントみたいに離れた世界にあるよりも、

同一のコードとして存在していたほうが処理系視点で扱いやすい

とかもありそう

JSにおいてもclass定義は型のようなもので、

ではこれを「コードから分離して書く」ならどうなるのか？というのは気になる

code:example.ts

function add(

left: number,

right: number

): number {

return left + right;

}

引数は

関数名が長くなるほど、型名が長くなるほど、こんな感じで改行したくなる

この書き方は JSDoc の書き方に近い

もしかしたら JSDoc をすんなり導入できるかもしれない

型定義が無いと、そもそもその関数が入力に何を求めていて何を出力するのかさっぱりわからないよね…？

部分的に変更できて何が良いかと言うと、型の柔軟性が高いからより厳密な型もより簡単に（回りくどいことをせずに）組めるということ

逆にJSDocを読み取るタイプの型チェッカーがどこまでできるのか知らないけれど、こういうことはできるのかな

code:possibleNull.ts

const foo = () => {

interface aryType {id: number, value?: unknown}

const possibleNull: aryType | undefined = ary.find(e => e.id === 1)

if (!possibleNull) return

// undefinedの可能性は消えたため、そのまま呼び出してもエラーにならない

console.log(possibleNull.id ** 10)

}

foo()

↓実行コマンド

型チェッカーの厳密度によると思うけれど、これができないなら厳密さの面でTypeScriptの方が勝るということになる

https://gyazo.com/f271de560904803aac565bfd7a764558

左の赤波線部分は「'possibleNull' は 'undefined' の可能性があります。」

code:possibleNull.js

// @ts-check

/**

* @typedef {Object} AryType

* @prop {number} id

* @prop {unknown} value

*/

const foo = () => {

/** @type {AryType[]} */

/** @type {AryType|undefined} */

const possibleNull = ary.find(a => a.id === 1);

if (!possibleNull) return;

console.log(possibleNull.id ** 10);

};

foo();

無視していいエッジケース

これは方法を知らないだけかもしれない

いつも readonly やから逆に使わんでいい説あるけど

code:example.js

/** @type {{ name: string, age: number }} */

const userInfo = {

"name": "山田太郎",

"age": 18,

};

declare …… 調べてみたけどこれが使えそうなときはインポート後に適宜@typeしてあげればいいか〜と思っている

例えばこれはJSと@ts-checkで書けません

code:ts

declare const scrapbox: Scrapbox;

scrapbox.PopupMenu.addButton({

title: "全→半",

onClick: (text) => text

.replaceAll("．", ". ")

.replaceAll("，", ", ")

.replaceAll("（", " (")

.replaceAll("）", ") ")

.replaceAll("　", " "),

});

code:js

// @ts-check

/** @typedef {import("jsr:@cosense/types@0.10.8/userscript").Scrapbox} Scrapbox */

// ↓型付けできない

scrapbox.PopupMenu.addButton({

title: "全→半",

onClick: (text) => text

.replaceAll("．", ". ")

.replaceAll("，", ", ")

.replaceAll("（", " (")

.replaceAll("）", ") ")

.replaceAll("　", " "),

});

pnpm/yarnならjsr入るけど("pnpm add jsr:@cosense/types"で)

Node.jsに詳しい人修正しといて～

パッケージ側でnpmベースシステムに対応する必要があるっぽい

code:txt

bsahd@bsahdarch ~ 0

$ mktemp -d

/tmp/tmp.jssQtROtLr

bsahd@bsahdarch ~ 0

$ cd /tmp/tmp.jssQtROtLr

bsahd@bsahdarch /tmp/tmp.jssQtROtLr 0

$ pnpm i jsr:@cosense/types

Packages: +1

+

Progress: resolved 1, reused 0, downloaded 1, added 1, done

dependencies:

+ @cosense/types <- @jsr/cosense__types 0.10.8

Done in 1.3s using pnpm v10.11.0

bsahd@bsahdarch /tmp/tmp.jssQtROtLr 0

$ node

Welcome to Node.js v23.11.1.

Type ".help" for more information.

import("@cosense/types")

Promise {

<pending>,

}

Uncaught:

at exportsNotFound (node:internal/modules/esm/resolve:314:10)

at packageExportsResolve (node:internal/modules/esm/resolve:661:9)

at packageResolve (node:internal/modules/esm/resolve:774:12)

at moduleResolve (node:internal/modules/esm/resolve:854:18)

at defaultResolve (node:internal/modules/esm/resolve:984:11)

at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:780:12)

at ModuleLoader.resolve (node:internal/modules/esm/loader:687:38)

at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:305:38) {

code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'

}

CDN経由でclassをimportしたいとき、JSDocではどうしようもない

code:typedefs/declare/OriginStorage.d.ts

export class OriginStorage {

constructor(storageName: string);

storageName: string;

// ︙(略)

}

}

code:import/OriginStorage.mjs

// @ts-check

/// <reference types="./../typedefs/declare/OriginStorage.d.ts" />

export { OriginStorage };

code:test.js

//@ts-check

import { OriginStorage } from "./import/OriginStorage.mjs";

const testStorage = new OriginStorage("testStorage"); // ←これは補完が効く

JSDocでもできてほしいなぁ

名前が定義されるタイミングでそれの型も定義されてて欲しくない？

code:example.js

/** @type {string} ユーザーの入力 */

const userInput = window.prompt();

拡張機能いくつか作ったから大分慣れたけどそれでも少し大きな拡張機能作るときは型宣言が無いと心配になる

まあ無い分の融通も受けてはいるんだけれども…

引数に何が入ってくるのか特定が非常に困難

今日deno+tsを使い始める => 井戸端にはts否定記事が書かれている

Pythonから入った身としてはコード内に型情報が入ることに特に違和感はない

(PythonではTSと同様の記法で型注釈をいれる)

表記的にすごく似ている

JavaScriptのダメなところを解消するためにはJSDocでは不十分だが、TypeScriptは十分であるとする理由

(素の)JavaScriptがダメなのはわかる

JSDocを認識させるissueは立っているが、活動していない

githubにあるコードの直リンクをimportできる

とはいえ、transpile不要という特徴が生かされる場面はあまり思いつかない

scrapbox内でコードを書く場合は重宝するかも

GitHub Pagesとかは自動でtranspileやってくれると認識しているので、それが強い理由かと言われると微妙

そのうちブラウザ内で直接TypeScriptが実行できるようになる気もする

(2024-09-19)ただ進展はそんなにない

難航してるっぽい

そうであれば難航するのも頷ける

JSDocとTypeScript、どちらを選ぶかはケースバイケースだと思います。JSDocの良さは、JavaScriptのコードベースで型の情報を追加できる点です。型情報を別のファイルに切り出さず、コード内にコメントとして書けるのは手軽で便利ですが、やはり型の厳密性や表現力ではTypeScriptにかなう部分は少ないですね。

TypeScriptはコンパイル時に厳密な型チェックが行われるため、開発時にエラーを早期に発見でき、バグを減らすことができます。特に大規模なプロジェクトでは、TypeScriptの方がコードの可読性とメンテナンス性を高めるため、選ばれることが多いです。しかし、JSDocはJavaScriptのコードベースでも利用でき、特に小規模なプロジェクトやライブラリでは手軽に使えるメリットがあります。

結局、プロジェクトの規模や求められる型の精度によって使い分けるのがベストです。TypeScriptをフル活用できる場合は、型の厳密性や他の言語との整合性を考えてTypeScriptが有利ですが、軽量なプロジェクトやすでにJavaScriptを使っているコードベースではJSDocが有用かもしれません。

綾坂こと.icon