Lesson 22 / الدرس 22

Reading documentation in English / قراءة التوثيق بالإنجليزية

Reference pages are not written to be read like prose, and reading them like prose is why they feel impenetrable. They have a fixed shape, five parts, and about forty words of vocabulary — this lesson gives you all three.

صفحات المرجع لا تُكتب لتُقرأ كالنثر، وقراءتها كالنثر هي سبب شعورك بأنها مستعصية. ولها شكل ثابت وخمسة أجزاء ونحو أربعين كلمة من المفردات — وهذا الدرس يعطيك الثلاثة.

A signature is a sentence

array_slice(array $array, int $offset, ?int $length = null): array
            └───┬───┘  └────┬────┘  └─────────┬────────┘   └─┬─┘
             required     required          optional      returns

?int      may be int, or null
= null    optional; this is what you get if you leave it out
|         'or' — string|false means either
...       takes any number from here on
: array   what comes back

Every reference page in every language uses this grammar. The demonstration lets you click each part of three real signatures to see what it is telling you — including the parts people skip, which are usually the ones that would have answered their question.

The forty words

English	In documentation it means	بالعربية
deprecated	Still works, will be removed — stop using it	مهجور
throws / raises	Fails by throwing, not by returning a value	يرمي استثناءً
returns false on failure	You must check — it will not throw	يعيد false عند الإخفاق
optional / defaults to	You may leave it out; this is what you get	اختياري / قيمته الافتراضية
immutable	Returns a new one; the original is untouched	غير قابل للتغيير
in place	Changes the thing you gave it	في مكانه
idempotent	Doing it twice is the same as once	جامد
case-insensitive	Upper and lower case are treated the same	لا يميّز حالة الأحرف
as of version X	Before X it behaved differently	ابتداءً من الإصدار كذا
see also	Often the function you actually wanted	انظر أيضًا

These ten, plus a handful you will pick up in a week, cover most of what a reference page says. Keep a note of any that stop you — the vocabulary of documentation is small and finite, which is the good news hiding behind the difficulty.

Read a reference page in this order, not top to bottom: the description sentence, then the examples, then the return section, then the parameter you are unsure about. Most pages are organised for completeness, not for the order a person needs them in — the examples answer the question ninety per cent of the time, and they are usually near the bottom. And when English is not your first language, read the examples first for exactly that reason: code is the same in every language.

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

<h1>Five functions I thought I knew</h1>

<h2>1. …</h2>
<pre>signature: …</pre>
<p>Returns on failure: …</p>
<p>Something I did not know: …</p>
<p>Changed between versions: …</p>

<h2>2. …</h2>
<p>…</p>

<h2>The assumption that was wrong</h2>
<p>I assumed … but the documentation says …</p>

<h2>Found through "see also"</h2>
<p>…</p>

Preview / المعاينة

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

1. What does ?int $length = null tell you?

بماذا يخبرك ?int $length = null؟

2. A function is documented as returning int|false. Why is if (strpos(...)) a bug?

دالة موثَّقة بأنها تعيد int|false. لماذا if (strpos(...)) خلل؟

3. In what order should you read a reference page?

Your task / مهمتك

Take five functions you already use without having read their documentation. Open the official reference for each and write down: the exact signature, what it returns on failure, one thing in the parameters section you did not know, and whether anything has changed between versions. At least one of the five must turn out to behave differently from what you assumed — if none does, you have chosen five you know too well, so pick harder ones. Then find one function through a "see also" link that you did not know existed and would have saved you code.

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

Five signatures copied exactly خمسة توقيعات منسوخة بالضبط
What each returns on failure ما تعيده كل واحدة عند الإخفاق
At least one assumption proved wrong افتراض واحد على الأقل ثبت خطؤه
One useful function found through "see also" دالة نافعة وُجدت عبر "انظر أيضًا"