عادت‌های برنامه‌نویسان حرفه‌ای در مستندسازی: ۷ کاری که سنیورها هر روز انجام می‌دهند

نویسنده: علی محمدی (کارشناس دیجیتال مارکتینگ)

آخرین بروزرسانی: ۱۸ شهریور ۱۴۰۵

یک تصور غلط رایج در بین برنامه‌نویس‌های ایرانی وجود دارد: «سنیورها آن‌قدر تجربه دارند که نیازی به مستند ندارند.» واقعیت دقیقاً برعکس است. اگر یک ماه در تیم مهندسی گوگل، متا یا استرایپ بنشینید، خواهید دید سنیورترین برنامه‌نویس‌ها بیشتر از همه وقت صرف نوشتن می‌کنند. نه چون کد را بلد نیستند، بلکه چون سال‌ها تجربه به آن‌ها ثابت کرده که مستندسازی، سریع‌ترین راه برای جلوگیری از اتلاف وقت تیم است.

این مقاله ۷ عادت مستندسازی برنامه‌نویس حرفه‌ای را بررسی می‌کند — عادت‌هایی که در تیم‌های سطح جهانی نهادینه شده‌اند و تفاوت واقعی بین یک سنیور و یک تازه‌کار را می‌سازند. این عادت‌ها را می‌توانید همین امروز شروع کنید، حتی اگر بقیه تیم شما هنوز باور نکرده‌اند.

عادت‌های برنامه‌نویسان حرفه‌ای در مستندسازی: ۷ کاری که سنیورها هر روز انجام می‌دهند

چرا برنامه‌نویس‌های سنیور برخلاف تصور، بیشتر مستند می‌نویسند؟

در یک نظرسنجی از Stack Overflow در ۲۰۲۳، برنامه‌نویس‌های با بیش از ۱۰ سال تجربه به طور متوسط ۲۲ درصد از زمان کاری خود را صرف نوشتن (شامل مستند، کامنت، طرح فنی، ایمیل فنی) می‌کردند. همین عدد برای برنامه‌نویس‌های زیر ۳ سال تجربه، ۹ درصد بود. اختلاف اینجاست.

چرا این اختلاف؟ چون سنیورها یاد گرفته‌اند که کد نوشتن آسان‌ترین بخش کار است. بخش سخت، هماهنگی است — با آینده خودت، با تیم فعلی، با تیمی که ۲ سال بعد این کد را نگهداری می‌کند. مستندسازی ابزار اصلی این هماهنگی است.

حالا ۷ عادت مشخصی که این هماهنگی را ممکن می‌کند:

۷ عادت مستندسازی برنامه‌نویسان حرفه‌ای

عادت ۱: قبل از نوشتن کد، یک Design Doc می‌نویسند

این تفاوت‌آفرین‌ترین عادت است. برنامه‌نویس جونیور معمولاً ایده را در ذهنش دارد و مستقیم می‌رود سراغ IDE. برنامه‌نویس سنیور اول یک سند ۱ تا ۳ صفحه‌ای می‌نویسد که این چیزها را روشن می‌کند:

  • مشکلی که قرار است حل شود چیست (نه راه‌حل، فقط مشکل)
  • گزینه‌های راه‌حل چه بودند و چرا این یکی انتخاب شد
  • چه اجزایی از سیستم تحت تأثیر قرار می‌گیرند
  • چه ریسک‌ها و trade-offهایی وجود دارد

گوگل به این سند Design Doc می‌گوید و رسماً بخشی از فرآیند مهندسی است. Rust و Kubernetes و بسیاری از پروژه‌های متن‌باز اسمش را RFC گذاشته‌اند. اسم مهم نیست؛ اصلش این است که فکر کردن روی کاغذ، هزار برابر ارزان‌تر از فکر کردن روی کد است.

مزیت واقعی: نوشتن Design Doc باعث می‌شود قبل از هدر رفتن یک ماه توسعه، ایراد اساسی راه‌حل مشخص شود. کد بد را می‌شود بازنویسی کرد، ولی یک ماه زمان از دست رفته را نه.

عادت ۲: هر تصمیم فنی مهم را در ADR ثبت می‌کنند

ADR (Architecture Decision Record) یک فایل کوتاه است که ثبت می‌کند: چرا این تصمیم فنی را گرفتیم. مثلاً «چرا PostgreSQL انتخاب کردیم، نه MongoDB» یا «چرا از event-driven architecture استفاده کردیم».

نکته کلیدی: ADR بعد از تصمیم نوشته نمی‌شود، بلکه در حین گرفتن تصمیم نوشته می‌شود. این کار خود فرآیند تصمیم‌گیری را عمیق‌تر می‌کند، چون مجبور می‌شوید گزینه‌ها را واقعی مقایسه کنید، نه فقط بر اساس ذوق شخصی انتخاب کنید.

چرا سنیورها این را می‌کنند: چون سال‌ها با کدی سر و کار داشته‌اند که کسی نمی‌داند چرا به این شکل نوشته شده. تنها راه فرار از این وضعیت، ثبت مکتوب چرایی است.

عادت ۳: کامنت‌هایشان "چرا" را توضیح می‌دهند، نه "چه کاری" را

یک تفاوت آنی که در Code Review می‌توانید یک سنیور را از یک جونیور تشخیص دهید:

کامنت جونیور:

// این تابع قیمت کل را حساب می‌کند

function calculateTotal(items) { ... }

کامنت سنیور:

// طبق فاکتور شماره ۲۲۱ حسابداری، تخفیف پلکانی

// فقط برای اقلام بالای ۱۰ عدد اعمال می‌شود

function calculateTotal(items) { ... }

کد خودش می‌گوید «چه کاری می‌کند». نیازی به تکرار نیست. اما هیچ کدی نمی‌تواند بگوید «چرا این قانون کسب‌وکاری اینجاست» یا «چرا این حالت خاص در نظر گرفته شده». این کار فقط از عهده کامنت انسانی برمی‌آید.

عادت ۴: README را قبل از commit اول به‌روز می‌کنند

در تیم‌های ضعیف، README همان چیزی است که Rails یا Next.js موقع ساخت پروژه تولید کرده و هیچ‌وقت دست نخورده. در تیم‌های حرفه‌ای، README اولین فایلی است که برنامه‌نویس سنیور به‌روز می‌کند، حتی قبل از اینکه یک خط کد بنویسد.

چرا؟ چون README مثل صفحه اول یک کتاب است. اگر خواننده در این صفحه گم شد، بقیه کتاب اهمیت ندارد. یک README حرفه‌ای در حد ۵ دقیقه به هر تازه‌واردی می‌گوید:

  • این پروژه چیست و چه مشکلی را حل می‌کند
  • چطور در ۱۰ دقیقه راه‌اندازی‌اش کنم
  • کجا مستندات بیشتر پیدا کنم
  • اگر گیر افتادم، به کی پیام بدهم

این عادت ساده به تنهایی می‌تواند زمان آنبوردینگ تیم شما را از هفته‌ها به روزها کاهش دهد.

عادت ۵: بعد از هر خطای تولید، post-mortem می‌نویسند

وقتی سایت دو ساعت پایین می‌آید، دو نوع تیم داریم:

  • تیم ضعیف: سریع مشکل را حل می‌کند، به رئیس گزارش شفاهی می‌دهد، فراموش می‌کند
  • تیم حرفه‌ای: سریع مشکل را حل می‌کند، بعد یک جلسه post-mortem بی‌سرزنش می‌گذارد و یک سند مکتوب تولید می‌کند

گوگل کتابی به نام Site Reliability Engineering دارد که فصلی کامل به این کار اختصاص داده و از ۲۰۱۶ استاندارد صنعتی شده است. اصل کلیدی این کار: Blameless — یعنی سرزنش فرد ممنوع. هدف پیدا کردن نقص در فرآیند است، نه در آدم.

برنامه‌نویس سنیور می‌داند که همان اشتباهی که بدون post-mortem رها شود، حتماً یک بار دیگر تکرار می‌شود. مکتوب کردن، تنها راه شکستن این چرخه است.

عادت ۶: مستندات را در PR با همان جدیت کد بازبینی می‌کنند

در تیم‌های ضعیف، Pull Request فقط شامل کد است. مستند یا وجود ندارد، یا اگر وجود دارد کسی نگاهش نمی‌کند. در تیم‌های حرفه‌ای، اگر feature جدید بدون مستند به‌روز شده باشد، PR مسدود می‌شود. دقیقاً همان‌طور که اگر تست نداشته باشد.

این عادت یک اصل ساده دارد: مستند باید همان چرخه ورژن‌کنترل، بازبینی و تأیید کد را طی کند. اگر مستند در فرآیند PR نیامد، هیچ‌وقت نوشته نمی‌شود یا زود منسوخ می‌شود.

عادت ۷: مستند را کنار کد نگه می‌دارند، نه در ابزار جداگانه

این عادت نامش Docs as Code است و در ۱۰ سال اخیر به استاندارد صنعتی تبدیل شده. اصل کار ساده است: مستندات فنی همان جایی نگهداری می‌شوند که کد است — در همان Git repository، با همان فرمت (Markdown)، همان چرخه ورژن، همان چرخه بازبینی.

چرا؟ چون مستندی که در Confluence یا Word جداگانه نگه داشته می‌شود، به سرعت از کد عقب می‌افتد. کسی که کد را تغییر می‌دهد، سراغ Confluence نمی‌رود. اما اگر مستند در همان فولدر کد باشد، تغییرش بخشی از همان PR خواهد بود.

نکته مهم: این به معنای رها کردن ابزارهای سطح بالاتر مثل باسینرژی یا Confluence نیست. مستندات فنی سطح کد → کنار کد. مستندات سطح فرآیند، تیم و سازمان → در ابزار مرکزی. این دو مکمل هم هستند، نه رقیب.

⭐ نکته‌: تفاوت واقعی جونیور و سنیور در مستندسازی

اگر بخواهم تمام این ۷ عادت را در یک اصل خلاصه کنم، این است:

جونیور فکر می‌کند مستندسازی کار «اضافه» است. سنیور می‌داند مستندسازی بخش خود کدنویسی است.

این تغییر ذهنی چهار پیامد عملی دارد:

  • جونیور می‌گوید: «فعلاً کد را می‌زنم، بعداً مستند می‌نویسم.» بعداً نمی‌آید.
  • سنیور می‌گوید: «feature بدون مستند تمام نشده. Definition of Done شامل مستند است.»
  • جونیور می‌نویسد: «این کلاس کاربر را مدیریت می‌کند.» (تکرار اسم کلاس)
  • سنیور می‌نویسد: «این کلاس چون قبلاً logic حساب کاربری و سفارش با هم بود، جدا شده تا هر تیم مسئول یکی باشد.» (زمینه‌ای که کد نمی‌تواند بگوید)

یک نقل قول معروف از مارتین فاولر: «هر احمقی می‌تواند کدی بنویسد که کامپیوتر بفهمد. برنامه‌نویس‌های خوب کدی می‌نویسند که انسان‌ها بفهمند.» — و مستند بخش جدانشدنی این «فهم انسانی» است.

چطور این ۷ عادت را در تیم خودتان جا بیندازید؟

عادت‌سازی یک‌شبه اتفاق نمی‌افتد. این نقشه راه سه‌ماهه، تجربه‌شده از تیم‌های موفق:

ماه اول: فقط عادت‌های ۳ و ۴

در ماه اول، هدف کوچک بگذارید: هر برنامه‌نویس فقط دو عادت. کامنت‌های «چرا» به جای «چه کاری» + به‌روز نگه داشتن README. این دو عادت نه به ابزار خاص نیاز دارد نه به تغییر فرآیند. فقط تغییر عادت شخصی است.

ماه دوم: افزودن عادت‌های ۶ و ۷

در ماه دوم، Docs Review را به بخش رسمی Code Review اضافه کنید و مستندات فنی را به Git منتقل کنید (اگر در Confluence یا Word هستند). این کار نیاز به توافق تیمی دارد.

ماه سوم: افزودن عادت‌های ۱ و ۲

در ماه سوم، برای featureهای بزرگ (بیش از یک اسپرینت) Design Doc اجباری کنید و برای تصمیم‌های معماری، ADR بنویسید. این‌ها فرآیندی هستند و نیاز به تمرین دارند.

عادت ۵ (Post-mortem) — منتظر اولین بحران بمانید

این عادت را نمی‌شود از قبل تمرین کرد. اما وقتی اولین حادثه بزرگ اتفاق افتاد، آماده باشید و یک جلسه post-mortem بی‌سرزنش برگزار کنید. یک بار انجام دادنش، فرهنگ تیم را برای همیشه عوض می‌کند.

سوالات متداول درباره عادت‌های مستندسازی برنامه‌نویس

۱. آیا نوشتن Design Doc قبل از کد، سرعت توسعه را کم نمی‌کند؟

در ظاهر بله، در واقعیت خیر. تحقیقات گوگل نشان داده که یک روز صرف Design Doc، به طور میانگین ۵ تا ۱۰ روز از دوباره‌کاری بعدی جلوگیری می‌کند. سرمایه‌گذاری با بازدهی ۵ برابری.

۲. اگر تیم ما کوچک است (۲ یا ۳ نفر)، آیا این عادت‌ها هنوز مهم است؟

حداقل ۳ عادت اول (Design Doc، ADR، کامنت‌های «چرا») حتی برای تیم تک‌نفره ارزش دارد، چون شما در آینده «تیم» خودتان هستید. کدی که ۶ ماه پیش نوشتید، مثل کد یک نفر دیگر است. مستندسازی، یادداشت برای شمای آینده است.

۳. ابزار مناسب برای Docs as Code چیست؟

برای مستندات فنی سطح کد: فایل‌های Markdown در همان Git repository. برای رندر و جستجو: MkDocs، Docusaurus یا GitBook. برای مستندات سطح تیم و سازمان: ابزارهایی مثل باسینرژی که مستندات را به تسک‌ها و کد وصل می‌کنند.

۴. تفاوت Design Doc و ADR در چیست؟

Design Doc قبل از توسعه یک feature بزرگ نوشته می‌شود و شامل جزئیات پیاده‌سازی است (چند صفحه). ADR در حین گرفتن یک تصمیم معماری نوشته می‌شود و فقط چرایی تصمیم را ثبت می‌کند (نیم تا یک صفحه). Design Doc زمان‌بندی محدود دارد؛ ADR برای همیشه نگه داشته می‌شود.

۵. اگر بقیه تیم این عادت‌ها را نمی‌پذیرند، من به تنهایی چه کنم؟

از عادت ۳ (کامنت‌های چرا) و عادت ۴ (README) شروع کنید. این‌ها به همکاری تیم نیاز ندارند و فقط شما را متمایز می‌کنند. بعد از چند ماه، تأثیرش را در Code Reviewها می‌بینید و تدریجاً بقیه هم پیروی می‌کنند. الگو بودن، مؤثرتر از سخنرانی است.

جمع‌بندی: عادت‌ها، نه شعارها

تفاوت واقعی بین یک برنامه‌نویس حرفه‌ای و یک تازه‌کار در مستندسازی، در عادت‌های روزمره است، نه در دانش تئوریک درباره اهمیت مستندسازی. هر ۷ عادتی که مرور کردیم، یک تغییر کوچک در روال روزانه است — نه یک انقلاب. اما وقتی این ۷ تغییر کوچک را کنار هم قرار می‌دهید، تفاوت بین یک تیم شلوغ‌کار و یک تیم قابل مقیاس‌پذیری را می‌سازند.

اما یک نکته را باید صادقانه گفت: هر ۷ عادت به یک زیرساخت درست نیاز دارد. اگر مستندسازی در ۳ ابزار مختلف پراکنده است، اگر تسک‌ها به مستند مربوطه لینک نیستند، اگر جستجو در مستندات نیم ساعت طول می‌کشد — عادت‌ها به مرور فرسوده می‌شوند.

باسینرژی دقیقاً برای این ساخته شده: پلتفرمی که هر تسک را به مستند مربوطه‌اش وصل می‌کند، تصمیم‌های فنی جایی مشخص برای ثبت دارند، و کل تیم روی یک منبع واحد حقیقت کار می‌کند. اگر می‌خواهید این ۷ عادت در تیم شما نهادینه شود، از پلن پرو باسینرژی با ۱۴ روز استفاده رایگان شروع کنید.

📚 منابع: