لینک کوتاه مطلب : https://hsgar.com/?p=3489

بدون منبع – مثلث مستندات

نمایه در مورد تماس

مثلث مستندسازی (یا چرا کد خود مستندسازی نمی شود)

در مقطعی از حرفه برنامه نویسی خود، احتمالاً چیزی مانند زیر شنیده اید:

“کد من خود مستند است”

یا

“مستندات کد IS”

مخالفت با این اظهارات ممکن است سخت باشد، به خصوص اگر از طرف فردی با تجربه تر از شما باشد. بسیاری از مشکلات این است که آنها اشتباه نمی کنند – خوب، آنها نیستند به صورت کامل اشتباه.

هدف مستندسازی

چرا ما چیزها را مستند می کنیم؟ اگر کد کافی بود، ما هرگز به آموزش، اسناد API یا هر چیز دیگری نیاز نداشتیم، درست است؟ چه نیازی از کاربران با داشتن کدی بیش از صرفاً برای برقراری ارتباط برنامه‌ها و خدمات ما برآورده می‌شود؟

واضح به نظر می رسد، اما اسناد وجود دارد تا بتوان به راحتی از کد استفاده کرد.

زمانی که برنامه در ذهن شماست و درک شهودی دارید، فراموش کردن این فوق‌العاده آسان است – اما به نظر تازه، آیا واقعاً به کد شما دسترسی به آن آسان است؟

چه، چرا، چگونه: مثلث مستندسازی

        What        
         /         
        /          
       /           
      /            
     /             
    /__________    
 Why            How 

در اینجا یک قانون سرانگشتی وجود دارد که من در چند جا دیده ام که در مورد چگونگی اطمینان از اینکه اسناد شما کاملاً کامل هستند تکرار شده است.

چرا مثلث؟ خوب، مثلث ها یک شکل قوی هستند، و هر ضلع از دست رفته آن را از نظر ساختاری کاملاً نامطلوب نشان می دهد – همانطور که از دست دادن اسناد حیاتی می تواند کد شما را به همان اندازه که برای دیگران غیرقابل استفاده باشد، کند.

چی (کد)

این همان چیزی است که مردم وقتی می گویند “کد من خود مستندسازی است” به دنبال آن هستند. کد واضح، مختصر و به خوبی نوشته شده به خودی خود نوعی سند است.

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

چرا (نظرات)

هر برنامه دارای یک تاریخچه است – چه به معنای بسیار پیش پا افتاده داشتن یک تاریخچه در کنترل نسخه، یا یک تاریخچه طولانی و مفصل از تغییراتی که برای رویارویی با چالش های مختلف متحمل شده است.

این مورد اخیر است که مهم ترین مورد توجه است چرا برخی از کدها در وضعیت فعلی خود وجود دارند.

نظرات اغلب وسیله ای برای این نوع یادداشت های حاشیه هستند. با توجه به اینکه این کار به دلایل بهینه سازی به این صورت انجام شده است یا مورد دیگر این بود که یک هک کثیف نشانه هایی را برای نگهدار بعدی باقی می گذارد تا بداند در ساخت این نرم افزار چه سازش هایی صورت گرفته است.

حفظ کد (میراث) بدون هیچ نظری، کمتر شبیه مکانیک بودن است و بیشتر شبیه باستان شناس بودن است.

چگونه (زمینه)

ضلع آخر مثلث اغلب نادیده گرفته می شود. ممکن است در رشته‌های اسنادی یا به‌هم پیوسته زندگی کند، به‌طور خودکار تولید شود یا در یک README با دقت ساخته شده باشد، اما همه این اطلاعات مربوط به زمینه‌ای است که کد در آن اجرا می‌شود.

هیچ برنامه ای در خلاء وجود ندارد. همیشه محیطی، سازمانی، فرآیندی وجود دارد که در آن زندگی می‌کند یا در خدمت آن است، و خارج از چارچوب گفته شده، کاملاً بی‌فایده است.

ناتوانی در تشخیص این موضوع، دلیل اصلی شماره یک کاربران جدید و توسعه دهندگان جوان است که قادر به انجام این کار ساده نیستند (از من در این مورد نقل قول نکنید، من هیچ داده ای ندارم).

یک آزمون تورنسل عالی برای این وجود دارد. فرآیند جدید یا خط لوله یا هر چیز دیگری را که پیاده‌سازی کرده‌اید (اعم از راه‌اندازی یک مخزن، اجرای یک کار و غیره) انتخاب کنید و فردی را پیدا کنید که از نظر فنی صلاحیت دارد اما با کاری که روی آن کار می‌کنید ناآشنا است. آنها را در مقابل آن پلونک کنید و خفه شو. مبارزه آنها را تماشا کنید و فقط در صورتی به آنها کمک کنید که واقعاً و واقعاً گیج شده باشند. این خیلی سریع به شما می گوید که کجا باید برای مستندسازی تلاش کنید.

هک – آن را بخشی از بررسی کد خود قرار دهید.

ارسال شده در 19/03/2021

← دریافت صفحات github برای کار با مولد سایت سفارشی من آموزش مجدد برای یادگیری →

لینک منبع

ارسال یک پاسخ

آدرس ایمیل شما منتشر نخواهد شد.