یادداشت ها

همانطور که از فصل <اطلاعات: ساختار> می دانیم ، یادداشت ها می توانند تک خطی : با شروع // و چند خطی: / * ... * / باشند.

ما معمولاً از آنها برای توصیف چگونگی و چرایی کار کد استفاده می کنیم.

در نگاه اول ، یادداشت کردن ممکن است بدیهی باشد ، اما افراد تازه کار در برنامه نویسی اغلب از آنها به اشتباه استفاده می کنند.

یادداشت های بد

تازه کارها تمایل دارند از یادداشت ها برای توضیح “آنچه در کد پیش می آید” استفاده کنند. مثل این:

// This code will do this thing (...) and that thing (...)
// ...and who knows what else...
very;
complex;
code;

اما در کد خوب ، مقدار چنین یادداشت های “توضیحی” باید حداقل باشد. به طور جدی ، کد باید بدون آنها قابل درک باشد.

یک قانون عالی در مورد آن وجود دارد: “اگر کد آنقدر نامشخص باشد که به یادداشت نیاز داشته باشد ، پس شاید به جای آن باید بازنویسی شود”.

دستور العمل: توابع فاکتور گیرنده

گاهی اوقات جایگزینی یک قطعه کد با یک تابع مانند اینجا مفید است:

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    // check if i is a prime number
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue nextPrime;
    }

    alert(i);
  }
}

نوع بهتر ، با تابع فاکتور گیرنده ی ‘isPrime’:

function showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) continue;

    alert(i);
  }
}

function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}

اکنون می توانیم کد را به راحتی درک کنیم. این تابع به خودی خود یادداشت می شود. به این کد توصیفی از خود گفته می شود.

دستور العمل: ایجاد توابع

و اگر ما یک “صفحه کد” طولانی مانند این داریم:

// here we add whiskey
for(let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// here we add juice
for(let t = 0; t < 3; t++) {
  let tomato = getTomato();
  examine(tomato);
  let juice = press(tomato);
  add(juice, glass);
}

// ...

بنابراین ممکن است نوع بهتری باشد که دوباره فاکتور بگیریم به توابع مانند:

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
  for(let i = 0; i < 10; i++) {
    let drop = getWhiskey();
    //...
  }
}

function addJuice(container) {
  for(let t = 0; t < 3; t++) {
    let tomato = getTomato();
    //...
  }
}

یک بار دیگر ، خود توابع می گویند چه اتفاقی می افتد. هیچ چیزی برای یادداشت وجود ندارد و همچنین ساختار کد هنگام تقسیم شده بهتر است. مشخص است که هر تابع چه کاری انجام می دهد ، چه چیزی را می گیرد و چه چیزی را برمی گرداند.

در واقعیت ، ما کاملاً نمی توانیم از یادداشت های “توضیحی” اجتناب کنیم. الگوریتم های پیچیده ای وجود دارد. و “ترفندهای” هوشمندانه ای برای اهداف بهینه سازی وجود دارد. اما به طور کلی باید سعی کنیم کد را ساده و توصیفی از خود نگه داریم.

یادداشت های خوب

بنابراین ، یادداشت های توضیحی معمولاً بد هستند. کدام یادداشت ها خوب هستند؟

معماری را شرح دهید

ارائه بررسی اجمالی سطح بالا از مؤلفه ها ، نحوه تعامل آنها ، جریان کنترل در موقعیت های مختلف چیست… به طور خلاصه – نگاه کلی به ظاهر کد. یک زبان ویژه UML برای ساختن نمودارهای معماری سطح بالا وجود دارد که کد را توضیح می دهد. قطعاً ارزش مطالعه را دارد.

پارامترهای تابع سند و استفاده : یک دستورالعمل ویژه JSDoc برای ثبت یک تابع وجود دارد: استفاده ، پارامترها ، مقدار برگشتی.

برای مثال:

/**
 * Returns x raised to the n-th power.
 *
 * @param {number} x The number to raise.
 * @param {number} n The power, must be a natural number.
 * @return {number} x raised to the n-th power.
 */
function pow(x, n) {
  ...
}

چنین یادداشت هایی به ما امکان می دهد بدون نگاه کردن به کد ، هدف از تابع را بفهمیم و از آن به روش صحیح استفاده کنیم.

راستی، بسیاری از ویراستارها مانند WebStorm می‌توانند آن‌ها را متوجه شوند و از آن‌ها برای فراهم کردن تکمیل خودکار و بعضی بررسی خودکار کدهای استفاده کنند.

همچنین، ابزارهایی مانند JSDoc 3 وجود دارند که می‌توانند از یادداشت‌ها مستنداتی در غالب HTML تولید کنند. شما می‌توانید درباره JSDoc در https://jsdoc.app بیشتر اطلاعات کسب کنید.

چرا تمرین اینگونه حل شد؟

چیزی که نوشته شده است مهم است. اما برای فهمیدن اینکه چه چیزی در حال رخ دادن است شاید چیزی که نوشته نشده است مهمتر باشد. چرا این تمرین دقیقا به این روش حل شد؟ قطعه کد جوابی نمی‌دهد.

اگر راه‌های زیادی برای حل این تمرین وجود دارد، چرا این یکی؟ خصوصا وقتی این راه‌حل واضح‌ترین آن‌ها نیست.

بدون چنین یادداشت‌هایی موقعیت زیر احتمال رخداد دارد:

1. شما (یا همکار شما) کدی که چند وقت پیش نوشته شده است را باز می‌کنید و می‌بینید که این کد «زیرمجموعه« است.
2. شما اینطور فکر می‌کنید: «چقدر آن زمان احمق وبدم و چقدر الان باهوش‌تر هستم» و کد با به روش «واضح‌تر و درست‌تر» بازنویسی می‌کنید.
3. …اصرار به بازنویسی خوب بود. اما در حین پروسه می‌بینید که روش «واضح‌تر» در واقع کمبود دارد. شما به سختی دلیل آن را به یاد می‌آورید چون خیلی وقت پیش آن را امتحان کردید. شما برمی‌گردید که این نوع کد نوشته شده را اصلاح کنید اما زمان هدر رفته.

به هر حال ، بسیاری از ویراستاران مانند WebStorm می تواند آنها را به خوبی درک کرده و از آنها برای ارائه خودکار و برخی بررسی خودکار کد استفاده کند.

همچنین ابزارهایی مانند JSDoc 3 که می تواند مستندات HTML را از یادداشت ها ایجاد کند. می توانید اطلاعات بیشتر در مورد JSDoc را در http://usejsdoc.org/ مطالعه کنید.

اگر راه های زیادی برای حل این مورد وجود دارد ، چرا این یکی؟ مخصوصاً وقتی که واضح ترین آن نیست.

     بدون چنین یادداشت هایی شرایط زیر امکان پذیر است:
     1. شما (یا همكار خود) كدی را كه چند وقت پیش نوشتید باز می كنید و می بینید كه "زیر حد بهینه" است.
     2. شما فکر می کنید: "من در آن زمان چقدر احمق بودم ، و چقدر باهوش تر شدم حالا" ، و با استفاده از نوع "واضح تر و صحیح تر" بازنویسی می کنید.
     3. ... میل به بازنویسی خوب بود. اما در این روند می بینید که در واقع فاقد راه حل "آشکارتر" است. شما حتی کم به خاطر می آورید ، چرا که مدتها قبل آن را امتحان کرده اید. شما به نوع صحیح بر می گردید ، اما زمان هدر رفته است.

     یادداشت ها که راه حل را توضیح می دهد بسیار مهم هستند. آنها به ادامه پیشرفت صحیح راه کمک می کنند.

آیا ویژگی های محسوس کد وجود دارد؟ کجا استفاده شده از آنها؟

اگر کد دارای چیزهای لطیف و ضد شهودی است ، قطعاً ارزش اظهار نظر را دارد.

خلاصه

نشانه مهم توسعه دهنده خوب ، یادداشت ها است: حضور آنها و حتی عدم حضور آنها.

نظرات خوب به ما امکان می دهد کد را به خوبی حفظ کنیم ، پس از تاخیر به آن برگردیم و از آن به طور مؤثر استفاده کنیم.

درباره این یادداشت کنید:

• معماری کلی ، نمای سطح بالا.
• استفاده از تابع.
• راه حل های مهم ، به ویژه هنگامی که فوراً آشکار نباشد.

از یادداشت خودداری کنید:

• این “نحوه کار کد” و “آنچه انجام می دهد” را می گوید.
• آنها را فقط زمانی قرار بده که غیرممکن کد ساده تر و توصیفی از خود شود که نیازی به آنها نداشته باشد.

ایادداشت ها برای ابزارهای مستندسازی خودکار مانند JSDoc3 نیز استفاده می شود: آنها را می خوانند و اسناد HTML تولید می کنند (یا اسناد را با قالب دیگر).