Lesson 18 / الدرس 18

Functions: naming a piece of work / الدوال: تسمية قطعة عمل

A function is a set of steps with a name, so you can run them from anywhere by saying the name. It is how a program stops being one long list and starts being something you can read.

الدالة مجموعة خطوات لها اسم، فتستطيع تشغيلها من أي مكان بقول الاسم. وهي كيف يكفّ البرنامج عن كونه قائمة طويلة واحدة ويبدأ في كونه شيئًا تستطيع قراءته.

function areaOfRectangle(width, height) {
  return width * height;
}

areaOfRectangle(3, 4)      12
areaOfRectangle(10, 2)     20

DEFINING it does nothing. CALLING it — the brackets — runs it.

That last line is the distinction beginners trip on: a function sitting in a file has not run and will not until something calls it. Run the demonstration to see the same work with and without a function.

Why functions, really

One place to change. When the tax rate moves, it moves once rather than in eleven places you have to find.
A name is documentation. calculateShipping(order) tells a reader what the next twenty lines are for without reading them.
You can test it. A function with inputs and an output can be checked on its own; a block of code in the middle of a page cannot.
It fits in your head. Reading one twenty-line function is possible; reading four hundred lines that do six things is not.

Three ways to write one

Written	Called	Note
function add(a, b) { … }	A declaration	Usable before it appears in the file
const add = function (a, b) { … }	An expression	Only after this line
const add = (a, b) => { … }	An arrow function	The short modern form
const add = (a, b) => a + b	A short arrow	One expression, returns it automatically

The last row is what you have been reading since lesson 16: p => p.price < 100 is a whole function. No braces means one expression, and its value is returned without writing return.

والسطر الأخير هو ما تقرؤه منذ الدرس 16: فـp => p.price < 100 دالة كاملة. فلا أقواس معقوفة تعني تعبيرًا واحدًا، وتُعاد قيمته دون كتابة return.

واستدعاء دالة بلا قوسين لا يشغّلها — بل يسلّمك الدالة نفسها. فـconsole.log(getTotal) يطبع الشيفرة وconst t = getTotal يجعل t اسمًا آخر للدالة لا لنتيجتها. ولا يظهر خطأ؛ بل تحصل ببساطة على شيء ليس رقمًا، وتظهر الحيرة بعد سطر واحد.

A good function does one thing, and its name says what. If the name needs the word "and", it is two functions — the same test as the commit messages in lesson 7 of the git course, for the same reason. validateAndSaveAndEmail is three things that will need to change at three different times.

والدالة الجيدة تفعل شيئًا واحدًا، ويقول اسمها ماذا. وإن احتاج الاسم كلمة "و" فهي دالتان — الاختبار نفسه من رسائل الـcommit في الدرس 7 من دورة git، للسبب نفسه. فـvalidateAndSaveAndEmail ثلاثة أشياء ستحتاج التغيير في ثلاثة أوقات مختلفة.

وسمِّ الدالة بفعل لأنها تفعل شيئًا: calculateTotal وformatDate وisValidEmail. فالدالة المسماة data أو info لا تخبر القارئ بشيء، واللحظة التي تتعثر فيها في إيجاد فعل هي عادةً لحظة ملاحظة أن الدالة تفعل أكثر من شيء.

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

<h1>The bill, in functions</h1>
<pre id="out"></pre>

<script>
  function subtotal(items) {
    return 0;
  }

  function serviceCharge(amount, rate) {
    return 0;
  }

  const lines = [];
  // test each one with three inputs

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

Preview / المعاينة

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

1. What is the difference between getTotal and getTotal()?

ما الفرق بين getTotal وgetTotal()؟

2. What is p => p.price < 100?

ما p => p.price < 100؟

3. What does a function name needing the word "and" suggest?

Your task / مهمتك

Take the bill calculator you wrote in lesson 3 and break it into named functions — one for the subtotal, one for the service charge, one for the split, one for formatting money. Each should do exactly one thing and be callable on its own. Then show each function being tested with three different inputs, printing the input and the result, so a reader can see it works.

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

Four functions, each doing exactly one thing أربع دوال تفعل كل واحدة شيئًا واحدًا
Every name is a verb كل اسم فعل
Each tested with three inputs, results printed كل واحدة مختبَرة بثلاثة مدخلات بنتائج مطبوعة
No function name contains "and" لا اسم دالة فيه "و"