Lesson 19 / الدرس 19

Parameters and return / الوسائط والإرجاع

What goes in and what comes out. Getting these two right is most of what makes a function reusable — and there is one silent mistake that makes a function look broken when it is not.

ما يدخل وما يخرج. وضبط هذين معظم ما يجعل الدالة قابلة لإعادة الاستخدام — وثمة خطأ صامت يجعل الدالة تبدو معطلة وهي ليست كذلك.

function priceWithTax(price, rate = 0.14) {
                   └────┬────┘  └────┬─────┘
                        │            └ a default, used if not given
                        └────────────── parameters: the names inside
  return price * (1 + rate);
}

priceWithTax(100)          114     rate defaults to 0.14
priceWithTax(100, 0.05)    105     the argument wins

The names in the definition are parameters; the values you pass are arguments. A default makes a parameter optional, which is often what turns two similar functions into one. Run the demonstration for the mistake that follows.

return ends the function immediately

Nothing after a return runs — it hands the value back and leaves. That is what makes the guard pattern from lesson 9 work: check the bad cases first, return out of them, and the rest of the function can assume everything is fine without three levels of nesting.

ولا يعمل شيء بعد return — فهو يعيد القيمة ويغادر. وذلك ما يجعل نمط الحارس من الدرس 9 يعمل: افحص الحالات السيئة أولًا وreturn منها، فتستطيع بقية الدالة افتراض أن كل شيء سليم بلا ثلاثة مستويات تعشيش.

What a call gives you back

Situation	What comes back
return value	That value
No return at all	undefined
return with nothing after it	undefined
A short arrow with no braces	The expression, automatically
A parameter not passed	undefined, unless it has a default

The second row is the silent mistake: a function that prints but does not return looks like it works, because you can see the output. The value is undefined, and the failure appears wherever you tried to use it.

والسطر الثاني هو الخطأ الصامت: فالدالة التي تطبع ولا تُرجع تبدو أنها تعمل لأنك ترى المخرَج. والقيمة undefined، ويظهر الفشل حيث حاولت استخدامها.

والطباعة ليست إرجاعًا. فـconsole.log(total) داخل دالة يريك الرقم ولا يعطي المستدعي شيئًا، فيبقى const t = getTotal() وt هي undefined — ويُنتج السطر التالي، الذي يحسب بها، NaN. وهذا أشيع عيب دوال عند المبتدئين، والدليل أن القيمة تبدو صحيحة على الشاشة وخاطئة في كل مكان آخر.

A function that takes more than about three parameters is usually asking for one object instead. createOrder(name, email, address, city, postcode, notes) is impossible to call correctly without checking the definition, and swapping two of them is a bug no error will catch. createOrder(details) with an object names every value at the call site.

والدالة التي تأخذ أكثر من نحو ثلاثة وسائط تطلب عادةً كائنًا واحدًا بدلًا منها. فـcreateOrder(name, email, address, city, postcode, notes) يستحيل استدعاؤها بشكل صحيح دون فحص التعريف، وتبديل اثنين منها عيب لن يمسكه أي خطأ. وcreateOrder(details) بكائن يسمّي كل قيمة عند موضع الاستدعاء.

Try it live / جرّب بنفسك

<h1>Inputs and outputs</h1>
<pre id="out"></pre>

<script>
  function formatPrice(piastres) {
    return '';
  }

  function orderTotal(details) {
    return 0;
  }

  const lines = [];
  // prove each one returns by using the result

  document.getElementById('out').textContent = lines.join('\n');
</script>

Preview / المعاينة

Check yourself / اختبر نفسك

1. A function prints the total with console.log and has no return. What does the caller get?

دالة تطبع المجموع بـconsole.log وبلا return. ماذا يحصل المستدعي؟

2. What does rate = 0.14 in a parameter list do?

ماذا تفعل rate = 0.14 في قائمة وسائط؟

3. A function needs six pieces of information. What is usually better?

Your task / مهمتك

Write four functions with clear inputs and outputs: one that formats a price, one that validates an email, one that takes an object of order details and returns a total, and one with a default parameter. Prove each one returns rather than prints by storing the result and using it in a further calculation. Then write the broken version of one — printing instead of returning — and show exactly where it fails.

اكتب أربع دوال بمدخلات ومخرَجات واضحة: واحدة تنسّق سعرًا، وواحدة تتحقق من بريد، وواحدة تأخذ كائن تفاصيل طلب وتعيد مجموعًا، وواحدة بوسيط افتراضي. وأثبت أن كل واحدة تُرجع لا تطبع بتخزين النتيجة واستخدامها في حساب آخر. ثم اكتب الصيغة المعطوبة لواحدة — تطبع بدل أن تُرجع — وأظهر بالضبط أين تفشل.

Four functions, each returning a value أربع دوال تُرجع كل واحدة قيمة
One takes an object rather than many parameters واحدة تأخذ كائنًا لا وسائط كثيرة
One has a default parameter, shown both ways واحدة بوسيط افتراضي، معروضة بالحالتين
The print-instead-of-return bug shown failing عيب الطباعة بدل الإرجاع معروض وهو يفشل