یک مشکل رایج در حفظ سیستم های قدیمی، درک اینکه چرا همه چیز به همین شکل است. لازم است تفکر توسعه دهندگان در آن زمان، درک زمینه توسعه، دانش سازندگان آنها و سناریوی سیاسی سازمان مسئول در نظر گرفته شود. این امر باعث می‌شود که توسعه‌دهنده/معمار حفظ استاندارد و انجام تعمیر و نگهداری سیستم به روشی واضح، منسجم و پایدار را دشوار کند.
فلسفه هدف در عمل
به نظر شخصی من وقتی کاری را انجام می دهیم باید دلیل عینی برای انجام آن داشته باشد. این دلیل می تواند منطقی، جهشی ایمانی، مذهبی، عاطفی یا میل باشد. اما باید دلیلی وجود داشته باشد. وقتی کارها را بدون هدف مشخص انجام می دهیم، تصمیمات تصادفی می گیریم که ما را به مسیری ناشناخته و با برنامه ریزی ضعیف هدایت می کند. ما به “تصادفی” اجازه می دهیم تا تصمیمات ما را بگیرد و باعث می شود کنترل زندگی خود را از دست بدهیم.
استفاده از “هدف” در توسعه نرم افزار
اگر مفهوم «هدف داشتن» را در توسعه نرم‌افزار به کار ببریم، می‌توانیم این ایده را استخراج کنیم که در یک سیستم ایده‌آل، هر تصمیمی که در طول چرخه عمر آن گرفته می‌شود، باید دلیل روشنی داشته باشد، از تصور آن تا نگهداری مداوم آن. تصمیمات اتخاذ شده باید راه حل را به سمت یک سناریوی برنامه ریزی شده، بر اساس الزامات روشن و کنترل شده توسط شیوه های مهندسی نرم افزار خوب هدایت کند، جایی که هر تصمیم خرد حرکتی را ایجاد می کند که سیستم را به وضعیت فعلی خود هدایت می کند. در این حالت، انتظار می رود که شامل ویژگی هایی مانند قابلیت نگهداری، وضوح، شهودی بودن، و قوانین کاملاً تعریف شده باشد و جزئیات تا حد امکان به تعویق افتاده تا تغییرات نهایی را تسهیل کند.
به سوی راه حل
اگر هر مرحله در چرخه عمر یک نرم افزار برای درک جهت آن مهم است، چگونه یک توسعه دهنده/معمار تازه وارد در یک سازمان، بدون تماس با سازندگان و نگهبانان آن، می تواند این تصمیمات کوچک گرفته شده در طول زمان را بدون تکیه بر کسر درک کند؟ پاسخ واضح است: مستندات. باشه، راحت اما این مستندات چگونه باید باشد؟
چرا اسناد بوروکراتیک و فنی نه؟
مستندات رایج معمولاً با الزاماتی احاطه شده است که هدفی کاملاً متفاوت از هدف ما به آن می دهد.
1. اسناد به طور مداوم به روز می شود
در مستندات فنی استاندارد، به روز رسانی و تکامل مداوم آن ضروری است، زیرا از سیستم پیروی می کند که از مدل کسب و کار پیروی می کند که دائماً تغییر می کند. اما آیا مستنداتی که ما به دنبال آن هستیم باید اینگونه باشد؟
اگر آنچه ما به دنبال آن هستیم ردیابی یک خط زمانی است که به ما امکان می دهد تصمیمات اتخاذ شده و دلایل آنها را ثبت کنیم، منطقی نیست که این لیست را به روز کنیم، زیرا تصمیمات اتخاذ شده در گذشته را نمی توان تغییر داد، فقط در زمان حال تصحیح کرد. . بنابراین، ما به اسنادی نیاز داریم که اطلاعات ثبت شده در گذشته را تغییر ندهند. بررسی کنید!
2. مستندسازی با مفاهیم صحیح
وقتی مستندات فنی را می خوانیم، انتظار داریم رکوردهای آن با مفاهیم ارائه شده و نحو صحیح آنها مطابقت داشته باشد. اما آیا این برای هدف ما اهمیت دارد؟
اسنادی که تصمیم گیری سیستم را ثبت می کنند لزوماً نیازی به صحیح بودن ندارند. می دانم، عجیب به نظر می رسد، اما اجازه دهید در این مورد بحث کنیم.
اگر در طول توسعه یک سیستم قدیمی، مسئولین آن زمان به دلیل کمبود دانش یا عدم بلوغ فنی، تصمیم اشتباهی گرفتند، نمی‌توان آن را در اسناد اصلاح کرد، زیرا بر تحلیل کلان تأثیر می‌گذارد که به ما امکان می‌دهد درک کنیم. وضعیت فعلی سیستم اگر بخواهیم بفهمیم که یک شخص چگونه عمل می کند، باید همانطور که او فکر می کند فکر کنیم.
بسیار خوب، بنابراین می‌توانیم در نظر بگیریم که مستندات ایده‌آل ما به دلیل اطلاعات نادرست نمی‌توانند به‌روزرسانی شوند، اما هنوز منطقی است که یک فیلد برای خطا ایجاد کنیم، که اطلاعات نادرست در نظر گرفته شده را همراه با استدلال درباره دلیل نادرست بودن آنها ثبت می‌کند.
3. مستندات بدون پیش نیاز
اسناد استاندارد معمولاً از خوانندگان خود می خواهد که به دنبال پایه ای باشند تا برخی از انتزاعات در طول مطالعه آنها روشن شود. بیایید مثال بزنیم: واکنش نشان دهید مستندات چارچوب نیاز به پیش نیازی برای درک زبان برنامه نویسی جاوا اسکریپت یا TypeScript دارد، زیرا از هر دو برای توسعه خود استفاده می کند. اما آیا در مستندسازی ایده آل ما باید پیش نیازهایی وجود داشته باشد؟
اگر ایده اصلی فقط اجازه دادن به خواننده است “همانطور که توسعه دهنده فکر می کرد فکر کنید” منطقی نیست که به زبان فنی باشد که خواننده را ملزم به داشتن دانش عمیق تر در مورد یک موضوع کند، زیرا در این مورد، پیشنهاد آن از صرفاً ثبت تصمیمات اتخاذ شده به تبدیل شدن به یک کتابچه راهنمای فنی تغییر می کند. ابزارها و تکنیک ها
شگفت انگیز! بنابراین مستندات ایده‌آل ما باید از فنی بودن خودداری کند و فقط بحث چرایی انجام کاری به روشی خاص را در اولویت قرار دهد.
قیاس دنیای واقعی
بیایید تصور کنیم که یک دفتر خاطرات می نویسیم. هدف این دفتر خاطرات ثبت زندگی، افکار و رویدادهای ماست. ما داستان های از قبل ضبط شده را پاک نمی کنیم زیرا می خواهیم حافظه را حفظ کنیم. ما مرتباً چیزهایی را که قضاوت می کنیم “نه چندان گویا” یادداشت می کنیم، اما با گذشت زمان متوجه می شویم که آنها اطلاعات ارزشمندی هستند. وقتی چیزی را یادداشت می‌کنیم، انتظار نداریم که در آینده هنگام بازخوانی، زمینه‌های خارجی را به خاطر بسپاریم – ما زمینه‌ها را می‌نویسیم تا درک بعدی خود را تسهیل کنیم. نوشتن در دفتر خاطرات معمولاً دارای یک “درمانی” بر ذهن ما تأثیر می گذارد، زیرا ما را وادار می کند در مورد اینکه چه کسی هستیم و چرا عمل می کنیم فکر کنیم.
واقعیت این است که دفترچه خاطرات چیزی طبیعی است که به آرامی جریان دارد و نباید به عنوان یک تعهد تلقی شود، بلکه باید به عنوان راهی برای گروه بندی افکار، رویدادها و تصمیمات زندگی مان تلقی شود تا بتوانیم فکر کنیم، به خاطر بسپاریم و از آن اجتناب کنیم. همان اشتباهات گذشته ما دوست داریم اسناد ما به همین صورت باشد.
پس این “اسناد” چگونه باید باشد؟
ما یک سری الزامات را از اسناد فنی استاندارد برای مقایسه آنها با نیاز خود در مدل پیشنهادی مطرح کردیم و از طریق آنها متوجه شدیم که باید تغییراتی ایجاد کنیم. اما کدام یک؟
- سوابق باید فقط خواندنی باشند: مستندات فقط باید نوشته شوند و تغییر داده نشوند و اجازه دهند وقایع با زمینه ها و افکارشان ثبت شوند، با توضیح مختصری در مورد اینکه چرا کاری همانطور که بوده انجام شده است، اما هرگز نباید تغییر داده شود.
- باید اشتباهی وجود داشته باشد: مستندات باید اجازه دهد که خطاهای فنی با توضیحات مربوطه برجسته شوند تا هیچ کس اشتباه را به درستی یا درست را به اشتباه تفسیر نکند.
- نباید به دانش فنی قبلی نیاز داشته باشد: مستندسازی نباید به دانش فنی به عنوان پیش نیاز خواننده برای درک محتوای آن نیاز داشته باشد، زیرا پیشنهاد خود را به عنوان کتاب رکورد بودن از دست می دهد و به مستندات فنی تبدیل می شود.
- نوشتن آن باید چیزی طبیعی باشد که تفکر انتقادی را برانگیزد: نوشتن مستندات نباید سنگین باشد. این فقط باید سابقه تفکر، زمینه و دلیلی باشد که چرا اقداماتی در طول توسعه و تکامل یک سیستم انجام شده است.
یک مدل کشف شده
ما آن را انجام دادیم! ما یک مدل ایده آل برای ثبت تصمیمات اتخاذ شده در برنامه های خود ایجاد کردیم که سبک، شهودی و مفید است.
تصمیم
- عنوان: استفاده از یک کتابخانه متمرکز برای استفاده از منابع مشترک برای همه برنامه ها
- تاریخ تصمیم گیری: 2025/05/01
- نوع تصمیم: معماری
-
توضیحات:
- زمینه: چندین API باید در یک بازه زمانی کوتاه و اغلب با توسعه موازی ایجاد شوند. همه آنها منابع مشترکی خواهند داشت که قابل استفاده مجدد هستند.
- انگیزه: استفاده مجدد از راهکارهای مختلف برای تمامی پروژه ها ضروری بود.
- جزئیات: تصمیم گرفته شد که کتابخانه ای با قابلیت های قابل استفاده مجدد که به قوانین تجاری مرتبط نیستند متمرکز شود تا توسط همه APIهای جدید ایجاد شده استفاده شود، جایی که آنها دائماً به روز می شوند (فرآیندی معمول برای به روز رسانی این کتابخانه در همه سیستم ها وجود خواهد داشت). در میان قابلیت های آن، آداپتوری که به API های HTTP اجازه می دهد با سیستم های WCF قدیمی ارتباط برقرار کنند، گنجانده خواهد شد.
-
مسئول: João das Couves، Jhali Rheinviei، Tsujiro Kisidane
اشتباه
- تصمیم اصلی: استفاده از یک کتابخانه متمرکز برای استفاده از منابع مشترک برای همه برنامه ها
- تاریخ نادرست: 2025/02/10
- شرح خطا: در طول توسعه، ما متوجه شدیم که حفظ مرجع خدمات WCF در آداپتور قدیمی بسیار پرهزینه است، زیرا هر به روز رسانی سرویس نیاز به آپلود نسخه جدیدی از کتابخانه دارد.
- تصحیح و دلیل: تصمیم گرفته شد که مرجع خدمات WCF قدیمی را از آداپتور داخل کتابخانه جدا کنیم و اکنون مرجع را به هر برنامه ای که خود آن را مدیریت می کند منتقل کنیم.
- مسئول Errata: تسوجیرو کیسیدانه
افکار نهایی
خوب، در نهایت، من فکر می کنم ما به هدف پیشنهادی در ابتدای مقاله دست یافتیم، درست است؟ شاید فکر می کنید این ایده باورنکردنی است، شاید فکر می کنید فوق العاده رقت انگیز است. شاید این ایده را از یک نویسنده واقعی یا شخص دیگری که قبلاً این ایده را ثبت کرده است، بدانید.
حقیقت این است که این فقط اشتراک ایده‌ای است که من هنگام اندیشیدن به مشکلات حفظ یک سیستم داشتم که در آن باید دریابید که چرا برای درک هدف آن اینگونه است. من به تحقیق در مورد اینکه آیا محتوایی مانند این قبلاً وجود دارد یا اینکه آیا نویسنده ای قبلاً این ایده را ارائه کرده است، متوقف نشدم. من فقط فکر کردم و نوشتم و پست کردم 👍.
به هر حال امیدوارم این مطالب مشکوک چیزی به زندگی شما اضافه کرده باشد. بزودی میبینمت دوستان
