مخاطبم غیرِ فنی است (مدیر/مشتری) — چهطور توضیح بدهم؟

فرمولِ سهگامِ غیرِفنی: **تشبیه + نتیجه + بدونِ اسمِ فنی**: "Think of it as a security guard at the door. This fix means faster logins for our users." (مثل نگهبانِ در ورودی. این فیکس یعنی ورودِ سریعتر برای کاربرها.) اسمِ فنی که لازم نیست نیاور — اگر پرسید، یکجملهای تعریفش کن و برگرد به نتیجه. این مهارت، درس ۸۲ (گفتگو با غیرِفنیها) را کامل میکند؛ فعلاً قالبِ تشبیه+نتیجه را تمرین کن.

در مصاحبه، توضیحِ کد چطور متفاوت است؟

در مصاحبه، بلند فکرکردن (thinking out loud) امتیاز است، نه ضعف: "Let me think out loud for a second… I'd start by clarifying the input size — that decides brute force or not." جوابِ کامل را نگه ندار؛ مسیرِ تصمیم را نشان بده — مصاحبهگر فنی، «صدای فکر» را میخواهد. و هر تصمیم را با چرا بگوی: "I'll use a hash map here because lookups are O(1)." — همین جملهها در درس ۶۱ برمیگردند و کامل میشوند.

درس ۵۳ از ۹۰ · توضیح‌دادنِ کد؛ «این تابع چه‌کاره است؟» به انگلیسی

تواناییِ نوشتنِ کد با کیفیت ثابت می‌شود؛ اما «توضیحِ کد» است که در ریلویو، جلسه و مصاحبه ارزیابی می‌شود. برای زبانِ دوم، این سخت‌ترین بخش فنی است چون هم‌زمان باید فکر و جمله و ساختار بدهی. راه‌حل همان قالب‌های ثابت است: وقتی اسکلتِ توضیح از حفظ باشد، مغز فقط روی محتوا می‌ماند.

این درس را با کدِ واقعیِ خودت تمرین کن: یک فایلِ را انتخاب کن و توضیحش را بلند بده — یا در پیامِ صوتی به خودت یا با اپِ مکالمهٔ آپورد. جلسهٔ بعدی که کسی پرسید «what does this do?», جوابِ تو آماده است.

سه سطحِ توضیح؛ کلی ← مسیر ← تصمیم

۱) دیدِ کلی (کلان): "At a high level, this service handles user authentication. It sits between the app and the user database." (در یک نگاه: این سرویس احرازِ هویت را هندل می‌کند — بینِ اپ و دیتابیسِ کاربر نشسته.) ۲) مسیرِ داده: "The flow goes like this: the client sends a token, we validate it against the auth service, then attach the user to the request." (جریان این‌طوره: کلاینت توکن می‌فرسته، ما با سرویسِ احراز چکش می‌کنیم، بعد کاربر رو به درخواست می‌چسبونیم.) ۳) تصمیم: "We cached the result because the auth call is the slowest part of the request." (کَش کردیم چون صدا زدنِ احراز کندترین قسمتِ درخواست‌ه.) — این سه سطح، کلِ توضیحِ فنی را پوشش می‌دهند؛ سطح را با مخاطب انتخاب کن: مدیر؟ سطحِ ۱. همکار؟ ۲ و ۳.

قالب‌های طلایی؛ جعبهٔ ابزارِ توضیح

قالب	کی	نمونه
Let me walk you through it.	شروعِ توضیحِ خط‌به‌خط	Let me walk you through the main function.
In a nutshell, …	خلاصهٔ یک‌نفسی	In a nutshell, it's a message queue for events.
The idea is (that)…	ایدهٔ اصلی	The idea is to keep the hot path fast.
Basically, …	ساده‌سازی	Basically, we retry three times, then give up.
Think of it as…	تشبیه	Think of it as a translator between two APIs.
The catch is…	نکتهٔ پنهان	The catch is: it only works on weekdays.
Long story short, …	جمع‌بندی	Long story short, we cut page load in half.

Let me walk you through it: the request hits the gateway, the gateway calls this service, and this service decides which database to read from.بذار خط‌به‌خط بگم: درخواست می‌رسه به گیت‌وی، گیت‌وی این سرویس رو صدا می‌زنه، و این سرویس تصمیم می‌گیره از کدوم دیتابیس بخونه.

پرسیده‌شدن از کدت؛ بدونِ حالتِ دفاعی

سوالِ کلاسیکِ ریلویو: "Why did you do it this way?" — سه قالبِ جوابِ حرفه‌ای: ۱) دلیل + بدیل: "I chose the in-memory cache for speed. Redis would be more durable, but for this use case it wasn't worth the extra hop." (سرعت بود؛ ردیس بادوام‌تره ولی برای این کِیس نمی‌ارزید.) ۲) اعترافِ محترمانه: "Honestly, that's a fair point — I can switch it to the async version." (نکتهٔ منصفانه‌ایه — می‌تونم به نسخهٔ async عوضش کنم.) ۳) مرزِ دانش: "I'm not sure about the trade-off there — let me check with the platform team." — هیچ‌کدام دفاعی نیستند؛ هر سه، جمله‌های مهندسِ خبره‌اند. و توضیحِ جریانِ طولانی را قطعه‌بندی کن: "First… then… and finally…" — شنونده همراهت می‌ماند.

گرامرِ عمیق‌تر: قالب‌های walk-through و زبانِ جریان

توضیحِ کد، سه فعلِ جریان دارد: goes (می‌رود): the request goes through the gateway · hits (برخورد می‌کند): it hits the cache first · returns (برمی‌گرداند): the service returns a signed URL. برای ترتیب: first, then, after that, finally — و برای مشروط‌ها: if the token is invalid, we reject early (اگر توکن نامعتبر بود، زود رد می‌کنیم — «reject early» اصطلاحِ محبوبِ کدِ تمیز). و برای طبقه: At a high level… (از بالا) · Drilling down… (پایین می‌رویم) · The gist is… (جِهتِ کلام اینه…).

At a high level, this service signs upload URLs. The request hits the auth middleware first; if the token is invalid, we reject early. Otherwise, we generate a signed URL and return it. The gist: the client never touches our storage credentials.از بالا: این سرویس URLهای آپلود رو امضا می‌کنه. درخواست اول به میدل‌ورِ احراز می‌خوره؛ اگه توکن نامعتبر باشه زود رد می‌کنیم. وگرنه URL امضاشده می‌سازیم و برمی‌گردونیم. جهتِ کلام: کلاینت هیچ‌وقت به اعتبارنامه‌های ذخیره‌سازِ ما دست نمی‌زنه.

گفتگو: لید می‌پرسد «چرا این‌طور نوشتی؟»

Lead: Walk me through this function — why generate the URL here and not in the gateway? — You: Fair question. The gateway doesn't have the storage credentials — by design.لید: این تابع رو برام توضیح بده — چرا URL رو همین‌جا می‌سازی نه تو گیت‌وی؟ — تو: سوالِ درستیه. گیت‌وی اعتبارنامهٔ ذخیره‌ساز رو نداره — عمداً.

Lead: So it's a security boundary thing? — You: Exactly. Centralizing the signing here means one audit point — if the gateway did it, we'd spread credentials wider than we need.لید: پس ماجرای مرزِ امنیتیه؟ — تو: دقیقاً. متمرکزکردنِ امضا این‌جا یعنی یه نقطهٔ حسابرسی — اگه گیت‌وی انجامش می‌داد، اعتبارنامه‌ها رو گسترده‌تر از نیاز پخش می‌کردیم.

Lead: Good reasoning. One nit — the function name could say so: signUploadUrl instead of handle. — You: Agreed — renaming now. Thanks, that's the kind of review that makes the codebase readable.لید: استدلالِ خوبیه. یه جزئی — اسمِ تابع می‌تونست همینو بگه: signUploadUrl به‌جای handle. — تو: موافقم — همین الان اسمش رو عوض می‌کنم. ممنون، این همون ریلویوئه که کدبیس رو خوانا می‌کنه.

اشتباه‌های رایجِ فارسی‌زبان‌ها در همین درس

این بخش را با یک قرارداد بخوان: هر ❌ یعنی «مغزِ فارسی‌زبانت این را می‌سازد و طبیعی است»، و هر ✅ یعنی «این همان چیزی است که گیرندهٔ انگلیسی‌زبان می‌شنود». خطاها اثرِ مستقیمِ ترجمهٔ ذهنیِ فارسی به انگلیسی‌اند؛ با هر جفت بلند تکرار کن تا شکلِ درست در گوشت نشست کند.

❌ I explain you this function.❌ توضیح‌دادنِ «به شما» را مغز با explain you می‌سازد؛ اما explain حرفِ اضافه می‌خواهد: explain it to you. راهِ حرفه‌ای اما قالبِ آماده است: Let me walk you through it — چهار کلمه که توضیح را به سفرِ مهندسی می‌برد.

✅ Let me walk you through this function.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ This function is for to check the token.❌ «برایِ بررسیِ توکن» را مغز با for to می‌سازد — ترکیبی که در انگلیسی وجود ندارد. توضیحِ کد، فعلِ ساده و مستقیم می‌خواهد: This function checks…؛ کارِ تابع با فعلش گفته می‌شود، نه با فلسفهٔ وجودیِ for.

✅ This function checks the token.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

❌ If the token is invalid, it gives error.❌ «خطا می‌دهد» را مغز با gives error ترجمه می‌کند؛ اما فعلِ فنیِ خطا throw است: it throws an error. همین یک فعل، گزارشِ باگ و توضیحِ کدت را از ترجمه به حرفه‌ای می‌برد.

✅ If the token is invalid, it throws an error.✅ شکل درست را دو بار بلند بگو؛ حالا یک بار در یک جملهٔ خودت.

تمرین‌های این درس — چهار قدم، بی‌عجله

توضیحِ کد مهارتِ زبانیِ جداست؛ تمرین‌ها را با کدِ واقعیِ ذهنِ خودت اجرا کن و بلند بگو.

سه سطحِ توضیح را برای یک سرویسِ احرازِ هویت بگو: دیدِ کلی ← مسیرِ داده ← تصمیم.
اصلاح کن: "I explain you: this function is for to check the token, and if it is empty it gives error."
قالبِ تشبیه را اجرا کن: «مثلِ مترجمِ بینِ دو API به آن فکر کن» + نتیجه برای مخاطبِ غیرِفنی.
جوابِ «چرا این‌طور نوشتی؟» را بگو: دلیل + بدیل — کشِ در حافظه در برابرِ ردیس.

پاسخ تمرین‌ها — اول خودت جواب بده، بعد باز کن

پاسخ تمرین ۱

نمونه: "At a high level, this service handles authentication. The flow goes: the client sends a token, we validate it against the auth service, then attach the user to the request. We cached the result because the auth call is the slowest part." — سه سطح، سه قالب؛ سطح را با مخاطب انتخاب کن.

پاسخ تمرین ۲

"Let me walk you through it: this function checks the token — if it's missing, it throws an error." — سه گرهِ یک‌جا باز شد: walk you through، فعلِ سادهٔ checks و throw. توضیحِ تمیز، کوتاه‌تر از ترجمهٔ درست است!

پاسخ تمرین ۳

"Think of it as a translator between two APIs. This fix means faster logins for our users." — تشبیه + نتیجه؛ برای مدیر و مشتری همین دو جمله کافی است و هیچ اسمِ فنی‌ای نمی‌خواهد.

پاسخ تمرین ۴

"I chose the in-memory cache for speed. Redis would be more durable, but for this use case it wasn't worth the extra hop." — دلیل + بدیلِ منصفانه؛ بی‌حالتِ دفاعی، با لحنِ مهندسِ خبره.

چالشِ امروز

🎯 یک تابعِ واقعی از کدت را امروز برای «هیچ‌کس» بلند توضیح بده — با Let me walk you through it شروع کن و با The gist is… تمام کن؛ ده‌دقیقه‌ای که جلسهٔ بعدی‌ات را جلو می‌اندازد.

نکات مکالمهٔ واقعی که کتاب‌ها کم می‌گویند

سه‌سطح را با مخاطب چین — مدیر: At a high level. همکار: مسیر + تصمیم. جونیور: خط‌به‌خط. سطحِ اشتباه، توضیحِ خوب را هدر می‌دهد.
چرا را با because not بگو — «We cache because the auth call is slow» — و بدیل را با otherwise: «Otherwise every request pays the penalty.» — جفتِ because/otherwise، منطقِ مهندسی را تمام‌قد می‌آورد.
تمرینِ بلندِ روزانه — روزی یک تابعِ خودت را برای «هیچ‌کس» بلند توضیح کن — ده دقیقه؛ جلسهٔ بعدی که پرسیدند، تو جلوتری.

🔑 جمع‌بندی این درس

توضیحِ کد سه‌سطحی: کلی (at a high level), مسیر (the flow goes…), تصمیم (we chose X because Y). جعبه‌قالب: walk you through it / in a nutshell / think of it as / the catch is. جوابِ «چرا این‌طور؟» سه‌قالبی: دلیل+بدیل، اعترافِ منصفانه، مرزِ دانش. تمرینِ این درس: کدِ واقعیِ خودت را بلند توضیح کن — جلسه‌ی بعد، این تمرین حرف اول را می‌زند.

توضیح‌دادنِ کد؛ «این تابع چه‌کاره است؟» به انگلیسی