太长了;
使用遗留代码库 – 我们中的许多人无法一次又一次地躲避 – 让我尝试使用 jsdoc 而不是 typescript。我必须揭露令人惊讶的真相!
首先让我们清理一下: jsdoc 或 ts 只是意味着在开发人员时间下(包括稍后审查、重用、在任何环境中查看该代码:git 网页、随机编辑器、chrome、firefox、. ..:devtool、vim、cat … );
第一乐章
只需打开你的编辑器,写下适当的注释来测试 jsdoc 是否正常工作。
/** @typedef { 'js' | 'jquery' | 'ts' | 'jsdoc' } phase; */ /** * on typing ' editor will popup string list. * * @type {phase} */ const badcase = 'react'; // !!!! lint alert !!!! /** @type {phase} */ const goodcase = 'jquery';
jsdoc 与 typescript
根据我的经验,jsdoc 能够替换 ts 代码,此外两者之间存在虫洞。
最大的jsdoc功能恕我直言:这是使用标准的js注释系统,所以不要破坏任何js代码,这个代码将在js能够运行的任何地方运行。
feature | jsdoc | typescript |
---|---|---|
compiling freedom | do not need compiling the code. | mandatory to compile |
dependency freedom | can working without any dependency | at least ts is your dependency |
Namespace freedom | don’t interfere types and other imports names. you can use same name of component and component type in react for example. | typesript names are identical including as any other referenct |
rework freedom | don’t need to change existing code, just insert a comment. | at least some part in your code need to be turn to ts |
legacy freedom | can be use even transform to typescript the project is not option. many legacy projects affected this situation. | need to push management to allow that modification |
maximalism freedom | don’t need to use every where. even you can use on a new commits, and after easy to search which is the new or reworked parts. | also enough to turn build system, and just part of code to ts |
future freedom | later can easy trasnlate to ts. under the hood this is use same technic, just different way. | need to work if decide to use js instead ts |
mindset freedom | because this is a comment your know well this is don’t made any type check at runtime for you as ts also. | ts is noising your code |
jsdoc 编辑经验
我可以在任何编辑器中编写jsdoc,但很少有人理解它。
节点模块体验
我还创建了一个 npm 模块:jsdoc-duck:一个 jsdoc 编码模块。这强调了如果没有 typescript,就不可能创建 jsdoc npm 模块。也许如果我花更多的时间来弄清楚 vite 构建参数,那么就可以找到正确的解决方案。但好消息是,如果不在 npm 中使用该模块,而是借用我们的代码:只需将 index.js 复制到某个位置 – 那么我们就可以节省时间来向我们的程序插入新的依赖项,并且不会发生任何事情如果模块所有者将模块转为其他东西。
jsdoc typescript 之间的虫洞
好消息是 typescript 和 jsdoc 相互兼容,只是 jsdoc 使用了一些不同的语法。但是您可以在打字稿中使用 jsdoc 模块类型,也可以在 JavaScript / js+jsdoc 程序中使用打字稿模块类型。所以最终决定权在你手中。
沿着黄砖路走
vs 代码示例展示了如何很好地看到 jsdoc 代码中的类型,在我看来,这给您的代码带来的噪音令人惊讶地减少了。
奖金
:: vs 代码片段
"@type": { "prefix": ["ty"], "body": ["/** @type {$0} */"], "description": "jsdoc type" }, "@typedef": { "prefix": ["td"], "body": ["/** @typedef {$1} foo */"], "description": "jsdoc typedef" },
:: jsdoc-duck 代码
(在此视图中语法突出显示无助于理解类型)。但是这个简短的程序是一个很好的例子,jsdoc 也可以使用 ts 的高级功能。
import { useMemo, useReducer } from "react"; /** * @template T - Payload Type * @typedef {T extends { type: infer U, payload?: infer P } ? { type: U, payload?: P } : never} ActionType */ /** @template AM - Actions Map @typedef {{ [K in AM['type']]: K }} Labels */ /** @template AM - Actions Map @typedef {{ [T in AM["type"]]: Extract<am type: t> extends { payload: infer P } ? (payload: P) => void : () => void }} Quack */ /** * @template ST - State * @template AM - Actions Map * @typedef {(state: ST, action: AM) => ST} Reducer */ /** * Factory function to create a typed action map. * @template AM - Actions Map * @param {Labels<am>} labelsObject - The keys representing action labels. * @param {function} dispatch - The dispatch function for actions. * @return {Quack<am>} The resulting typed action map. */ export const quackFactory = (labelsObject, dispatch) => Object .keys(labelsObject) .reduce( /** * @arg {Quack<am>} acc * @arg {keyof Labels<am>} type * @return {Quack<am>} */ (acc, type) => ({ ...acc, [type]: (payload) => {dispatch({ type, payload });} }), {}); /** * A factory hook to create a state and a typed dispatch functions * @exports useDuck * @template AM - Actions Map * @template ST - State Typer * @param {(st: ST, action: AM) => ST} reducer - The reducer function to manage the state. * @param {ST} initialState - The initial state value. * @return {[ST, Quack<am>]} The current state and a map of action dispatch functions. */ export const useDuck = (reducer, initialState, labels) => { const [state, dispatch] = useReducer(reducer, initialState); const quack = useMemo( () => quackFactory(labels, dispatch), [dispatch, labels] ); return ([state, quack]); }; </am></am></am></am></am></am></am>
快乐编码,挖掘而不是添加依赖
暂无评论内容