پرش به محتوای اصلی
فهرست مطالب

فصل ۸ از ۱۰

خطاهای رایج

۶ دقیقه مطالعهبه‌روزرسانی

اینجا فهرست ۳۳ باگ واقعی رو می‌بینید که بارها توی پروژه‌ها و کتابخونه‌های مختلف تکرار شدن، همراه با نشونهٔ هر باگ و راه حلش. بیشتر این باگ‌ها رو موقع نوشتن همین راهنما و تست کردن کتابخونه‌ها از نزدیک دیدیم و بازتولید کردیم!

# خطا / باگ چطوری خودش رو نشون می‌ده؟ راه‌حل درست
۱ استفاده از الگوریتم چرخهٔ ۲۸۲۰ ساله (بیرشک) تمام تاریخ‌های بین ۲۰ مارس ۲۰۲۵ تا ۲۰ مارس ۲۰۲۶ (کل سال ۱۴۰۴) یک روز جابه‌جا می‌شن و ۳۰ اسفند ۱۴۰۳ اصلا وجود نداره! استفاده از فرمول ۳۳ ساله + جدول اصلاح، یا یکی از کتابخونه‌های تیک‌خورده (✅) در بخش ۶
۲ فرض کردن اینکه کبیسه‌ها همیشه ۴ سال یک‌بارن (y % 4 == 3 و مشابه اون) از سال ۱۴۰۸ به بعد به خطا می‌خوره (چون فاصلهٔ کبیسهٔ ۱۴۰۳ تا ۱۴۰۸ پنج ساله است) استفاده از فرمول استاندارد ۳۳ ساله + جدول اصلاح
۳ استفاده از تقسیم معمولی (/ و %) روی اعداد منفی برای سال‌های منفی یا مقادیر میانی منفی یک روز خطا می‌ده و پیدا کردنش خیلی سخته استفاده از تقسیم کف (Floor division) طبق بخش ۳
۴ اضافه کردن ماه از طریق تبدیل به میلادی «۱ مهر + ۱ ماه» به جای «۱ آبان» می‌شه یه روز دیگه! اضافه کردن ماه مستقیما روی سال و ماه شمسی و محدود کردن شمارهٔ روز
۵ اضافه کردن ماه بدون محدود کردن (Clamp) شمارهٔ روز «۳۱ شهریور + ۱ ماه» یا خطا پرتاب می‌کنه (مثل shamsi_date) یا سرریز می‌شه به ۱ آبان! محدود کردن روز به حداکثر طول ماه مقصد (days_in_month)
۶ فرض کردن اینکه ۲۹ اسفند همیشه آخرین روز ساله روز ۳۰ اسفند در سال‌های کبیسه از گزارش‌ها و Datepickerها جا می‌افته گرفتن طول اسفند از تابع days_in_month(y, 12)
۷ اشتباه وارد کردن طول ماه‌ها در کد (مثلا ۳۱ روزه گرفتن مهر) از اول پاییز به بعد تمام تاریخ‌ها یک روز جابه‌جا می‌شن ۶ ماه اول ۳۱ روزه، ۵ ماه بعدی ۳۰ روزه، اسفند ۲۹ یا ۳۰ روزه
۸ تبدیل تاریخ اسناد قدیمی (قبل از سال ۱۳۰۴) با فرمول امروزی تاریخ نامه‌ها و اسناد دورهٔ قاجار چند روز پس‌وپیش می‌شه قبل از ۱۳۰۴ طول ماه‌ها برجی و متغیر بود؛ برای تاریخ‌های تاریخی از مبدل قدیمی در persian-calendar/calendar استفاده کنید
۹ استفاده از کتابخونه‌ها خارج از بازهٔ پشتیبانی‌شون پرتاب شدن خطا یا برگردوندن تاریخ غلط برای سال‌های دور (مثلا jalaali-js بعد از سال ۳۱۷۷ خطا می‌ده) محدود کردن و اعتبارسنجی بازهٔ ورودی
# خطا / باگ چطوری خودش رو نشون می‌ده؟ راه‌حل درست
۱۰ تبدیل تاریخ بر اساس ساعت UTC یا ساعت سرور (به جای تایم‌زون کاربر) بین ساعت ۱۲ شب تا ۳:۳۰ بامداد به وقت ایران، تاریخ «امروز» هنوز تاریخ دیروز رو نشون می‌ده! اول تاریخ رو در تایم‌زون Asia/Tehran (یا تایم‌زون کاربر) بگیرید و بعد به شمسی تبدیل کنید
۱۱ قدیمی بودن دیتابیس تایم‌زون سیستم (قبل از tzdata 2022b) از بهار ۱۴۰۲ به بعد، ساعت‌ها در بهار و تابستان ۱ ساعت جلو می‌رن و تاریخ‌ها حوالی نیمه‌شب اشتباه می‌شن آپدیت کردن سیستم‌عامل، JDK، ‏ICU، ‏Node.js و پکیج tzdata (ایران از شهریور ۱۴۰۱ ساعت تابستانی نداره)
۱۲ هاردکد کردن +03:30 در کد برنامه ساعت تاریخ‌های ثبت‌شده در تابستان‌های قبل از ۱۴۰۲ یک ساعت اشتباه نشون داده می‌شه استفاده از نام استاندارد IANA یعنی Asia/Tehran
۱۳ تبدیل داده‌های «فقط تاریخ» (مثل تاریخ تولد) به نیمه‌شب UTC و نمایش به وقت محلی برای کاربرهایی که در کشورهای غرب گرینویچ (اروپا/آمریکا) هستن، تاریخ تولد یک روز عقب می‌افته! نگه داشتن تاریخ به عنوان تاریخ بدون ساعت (LocalDate، DateOnly، date)
۱۴ خوندن Timestamp خروجی parse در یک تایم‌زون دیگه در PHP، خروجی IntlDateFormatter::parse('1404/01/01') اگر در UTC فرمت بشه، می‌شه 2025-03-20! خوندن و فرمت کردن Timestamp در همون تایم‌زونی که parse شده است
۱۵ تفاوت new Date('2025-03-21') (در UTC) با new Date(2025, 2, 21) (به وقت محلی) در JS بسته به تایم‌زون سیستم کاربر، تاریخ یک روز جابه‌جا می‌شه مشخص کردن صریح تایم‌زون، یا استفاده از PlainDate در Temporal

۳. کتابخانه‌ها و لایسنس‌ها

پیوند به بخش ۳. کتابخانه‌ها و لایسنس‌ها
# خطا / باگ چطوری خودش رو نشون می‌ده؟ راه‌حل درست
۱۶ استفاده از dayjs + پلاگین jalaliday (نسخهٔ 3.1.1) در تمام سال‌های کبیسهٔ میلادی، از ۱ ژانویه تا ۲۹ فوریه تبدیل میلادی به شمسی ۱ روز خطا داره (مثلا 2024-01-20 رو به جای ۱۴۰۲/۱۰/۳۰ می‌ده ۱۴۰۲/۱۱/۰۱!) تا زمان رفع باگ، از کتابخونهٔ دیگه‌ای استفاده کنید و با data/test-vectors.csv تستش کنید
۱۷ استفاده از پکیج پایتونی khayyam به خاطر چرخهٔ ۲۸۲۰ ساله، همین الان برای سال‌های ۱۴۰۳ و ۱۴۰۴ تاریخ اشتباه می‌ده مهاجرت به persiantools یا jdatetime
۱۸ استفاده از gem روبی parsi-date (نسخهٔ 0.5.1) در سال‌های کبیسه‌ای مثل ۱۴۰۸ (مارس ۲۰۲۹) تاریخ نامعتبر تولید می‌کنه استفاده از پیاده‌سازی Ruby موجود در همین مخزن
۱۹ نسخه‌های قدیمی ICU (نسخهٔ 76.1 و قبل‌تر) در مرورگرهای قدیمی، Node.js ≤ 23 و اندرویدهای قدیمی تا سال ۱۵۰۲ کاملا درسته، اما از ۱۵۰۳ به بعد جدول اصلاح رو نداره برای برنامه‌های امروزی هیچ مشکلی نداره (تا سال ۲۱۲۴ میلادی دقیقه)
۲۰ استفاده از کتابخونه‌های دارای مجوز GPL در پروژه‌های تجاری/بسته نقض کپی‌رایت و الزام قانونی به متن‌باز کردن کل پروژه بررسی لایسنس کتابخونه‌ها قبل از نصب (مثلا persian-calendar/calendar مجوز GPL-2.0+‎ داره)

۴. متن، فونت و رابط کاربری (UI)

پیوند به بخش ۴. متن، فونت و رابط کاربری (UI)
# خطا / باگ چطوری خودش رو نشون می‌ده؟ راه‌حل درست
۲۱ حروف ي و ك عربی در نام ماه‌ها یا جست‌وجوی کاربر سرچ کار نمی‌کنه و مقایسهٔ رشته‌ها شکست می‌خوره (چون "دي" !== "دی") یکسان‌سازی (Normalize) ورودی‌ها به ی (U+06CC) و ک (U+06A9) فارسی
۲۲ نمایش ارقام عربی (٤٥٦) به جای ارقام فارسی (۴۵۶) شکل اعداد ۴، ۵ و ۶ در رابط فارسی غریبه و ناهماهنگ به نظر می‌رسه استفاده از لوکیل fa-IR (سیستم عددنویسی arabext)
۲۳ پاس دادن مستقیم رشتهٔ فارسی به parseInt('۱۴۰۴') برگردوندن NaN در جاوااسکریپت تبدیل ارقام فارسی و عربی به انگلیسی (0-9) قبل از تبدیل به عدد
۲۴ فرمت کردن عدد سال با Formatter معمولی اعداد نمایش سال به شکل «۱٬۴۰۴» (با ویرگول هزارگان!) ست کردن useGrouping: false یا استفاده از Formatter تاریخ
۲۵ نوشتن «سه شنبه» (با فاصله) یا «سهشنبه» (چسبیده) ظاهر نادرست و غیراستاندارد در رابط کاربری نوشتن «سه‌شنبه» با نیم‌فاصله (U+200C) در خروجی، و قبول کردن هر سه شکل در ورودی
۲۶ شروع شدن جدول تقویم از یکشنبه یا دوشنبه کاربرهای ایرانی موقع انتخاب روز هفته دچار اشتباه می‌شن شروع جدول هفته از شنبه و با چیدمان راست‌به‌چپ (RTL)
۲۷ رها کردن رشتهٔ تاریخ وسط متن دوسویه (فارسی + انگلیسی) جابه‌جا شدن جای سال و روز در نمایش (01/01/1404 به جای 1404/01/01) گذاشتن تاریخ داخل تگ <bdi> یا کاراکترهای ایزولهٔ U+2068…U+2069
۲۸ استفاده از dateStyle: 'full' در Intl برای زبان فارسی خروجی نامأنوس «۱۴۰۴ فروردین ۱, جمعه» ساختن عبارت «جمعه ۱ فروردین ۱۴۰۴» با استفاده از formatToParts (بخش ۵)
۲۹ مرتب‌سازی (Sort) تاریخ‌ها به صورت رشتهٔ متنی بدون صفر اول تاریخ 1404/1/9 بعد از 1404/1/10 قرار می‌گیره! مرتب‌سازی بر اساس تاریخ میلادی/JDN، یا اضافه کردن صفر دو رقمی (1404/01/09)
# خطا / باگ چطوری خودش رو نشون می‌ده؟ راه‌حل درست
۳۰ ذخیره کردن تاریخ فقط به صورت رشتهٔ متنی شمسی در دیتابیس کوئری زدن سخت می‌شه، توابع تاریخ دیتابیس از کار می‌افتن و مرتب‌سازی باگ می‌خوره ذخیره کردن به صورت تاریخ استاندارد میلادی (date / timestamptz) و تبدیل به شمسی در لایهٔ نمایش
۳۱ گذاشتن تاریخ شمسی داخل فیلد استاندارد ISO 8601 در API کلاینت‌ها و کتابخونه‌ها رشتهٔ 1404-01-01 رو سال ۱۴۰۴ میلادی (قرن پانزدهم!) تفسیر می‌کنن ارسال تاریخ میلادی در فیلد اصلی و گذاشتن تاریخ شمسی در فیلد جداگانه مثل date_fa
۳۲ هاردکد کردن تعطیلات رسمی داخل کد برنامه با اولین تغییر قانون یا جابه‌جا شدن ماه‌های قمری، تعطیلات برنامه اشتباه می‌شه خوندن تعطیلات از روی فایل/سرویس دادهٔ قابل آپدیت
۳۳ استفاده از تقویم‌های islamic یا islamic-umalqura برای تعطیلات قمری ایران تعطیلاتی مثل عید فطر یا عاشورا در بعضی سال‌ها یک روز خطا دارن استفاده از جدول شروع ماه‌های قمری ایران (بخش ۷: تعطیلات)