JSDOC: سلاح مخفی شما برای افزودن انواع به JavaScript (بدون تعمیرات اساسی TypeScript)

TypeScript ابزاری خارق العاده برای افزودن تایپ استاتیک به JavaScript است، خطاها را زود هنگام و باعث می شود که کد های بزرگ کد را کنترل کنند. اما بیایید صادق باشیم ، گاهی اوقات مهاجرت کامل Typescript می تواند مانند کوهنوردی کوه اورست باشدبشر چه می شود اگر می توانستید بیشترین مزایای یک سیستم تایپ شده را بدون تعمیرات اساسی بدست آورید؟ برای افزودن انواع ، سلاح مخفی خود را وارد کنید. (و مستندات عالی!) به پروژه های JavaScript خود.

قدرت JSDOC

jsdoc ، آن نظرات آشنا بالاتر از کد شما، می تواند بیشتر از توضیح آنچه توابع شما انجام می دهد ، انجام دهد. آنها همچنین می توانند انواع را تعریف کنند! با استفاده از @typedef وت @type شما می توانید پیچیده ایجاد کنید ، تعاریف نوع قابل استفاده در پرونده های JavaScript خودبشر این به شما امکان می دهد تا بدون پیچیدگی کامل TypeScript ، ایمنی نوع را اضافه کرده و خوانایی کد را بهبود بخشید.

چرا JSDOC ممکن است برای شما مناسب باشد

• پروژه های کوچکتر: برای پروژه های کوچکتر ، سربار یک تنظیم کامل Typescript ممکن است بیش از حد باشد. JSDOC روشی سبک برای اضافه کردن ساختار و مستندات ارائه می دهد.
• اتخاذ تدریجی: JSDOC می تواند یک سنگ پله فوق العاده به سمت Typecript باشد. شما می توانید با JSDOC شروع کنید ، پرونده های اعلامیه را تولید کنید و در صورت لزوم به تدریج به Full TypeScript انتقال دهید.
• کد های جاوا اسکریپت موجود: مهاجرت یک پایگاه بزرگ کد جاوا اسکریپت به TypeScript می تواند دلهره آور باشد. JSDOC به شما امکان می دهد انواع مختلفی را معرفی کنید ، بدون اینکه همه چیز را به طور همزمان بازنویسی کنید.
• مستندات به عنوان یک شهروند درجه یک: JSDOC بر مستندات تأکید می کند ، که صرف نظر از سیستم تایپ شما بسیار مهم است. یک پایگاه کد به خوبی مستند همیشه یک مزیت است.

تعریف انواع با @typedef وت @type

اینجا جایی است که جادو اتفاق می افتد. بیایید ببینیم که چگونه انواع را با استفاده از JSDOC تعریف می کنید:

/**
 * @typedef {Object} Point
 * @property {number} x - The x-coordinate.
 * @property {number} y - The y-coordinate.
 */

/**
 * Calculates the distance between two points.
 * @param {Point} p1 - The first point.
 * @param {Point} p2 - The second point.
 * @returns {number} The distance between the points.
 */
function distance(p1, p2) {
  const dx = p2.x - p1.x;
  const dy = p2.y - p1.y;
  return Math.sqrt(dx ** 2 + dy ** 2);
}

/**
 * @type {Point}
 */
const originPoint = { x: 0, y: 0 };

console.log(distance(originPoint, { x: 3, y: 4 }));

در این مثال:

• @typedef {Object} Point: یک نوع نقطه را به عنوان یک شی با خصوصیات x و y ، هر دو عدد تعریف می کندبشر
• @param {Point} p1: از نوع نقطه برای مشخص کردن نوع پارامتر P1 استفاده می کندبشر
• @param {Point} p2: از نوع نقطه برای مشخص کردن نوع پارامتر P2 استفاده می کندبشر
• @type {Point}: با نوع نقطه ، نقطه OriginPoint را ثابت می کندبشر

تولید کننده .d.ts پرونده ها

واقعی قدرت jsdoc انواع وقتی می آید ایجاد پرونده های اعلامیه TypeScript (.d.ts)بشر کامپایلر TypeScript (TSC) می تواند نظرات JSDOC شما را تجزیه کند و این پرونده ها را برای شما ایجاد کند. این بدان معناست که شما حتی در هنگام نوشتن JavaScript ساده ، نوع بررسی و تکمیل کد را در IDE خود دریافت می کنید!

در اینجا اساسی است tsconfig.json پیکربندی:

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "declaration": true,
    "allowJs": true,
    "emitDeclarationOnly": false, // Set to true to ONLY emit .d.ts files
    "esModuleInterop": true
  },
  "include": ["./src/**/*.js"],
  "exclude": ["node_modules"]
}

سپس ، اجرا کنید npx tsc (یا tsc در صورت نصب جهانی) در فهرست پروژه خود. این باعث تولید می شود .d.ts پرونده های موجود در خارج از کشور (./ در این مثال). در زیر می توانید پرونده اعلامیه TSC را برای شما ایجاد کنید

بهترین های هر دو جهان

jsdoc با تولید نوع یک میانه فوق العاده فراهم می کندبشر شما می توانید از مزایای استفاده از نوع ایمنی و مستندات بهبود یافته بدون سربار کامل TypeScript لذت ببرید. این یک گزینه عالی برای پروژه هایی است که در آن یک مهاجرت کامل با نسخه امکان پذیر یا ضروری نیست، به شما امکان می دهد انواع مختلفی را معرفی کرده و کیفیت کد خود را با گذشت زمان بهبود بخشید.

بنابراین ، دفعه بعد که به فکر اضافه کردن انواع به JavaScript خود هستید، بلافاصله به تبدیل کامل Typescript پرش نکنید. JSDOC را در نظر بگیرید – ممکن است دقیقاً همان چیزی باشد که شما نیاز دارید.

و مثل همیشه
برنامه نویسی مبارک 🧑🏻‍💻