فصل ۸ از ۱۰
خطاهای رایج
۶ دقیقه مطالعهبهروزرسانی
اینجا فهرست ۳۳ باگ واقعی رو میبینید که بارها توی پروژهها و کتابخونههای مختلف تکرار شدن، همراه با نشونهٔ هر باگ و راه حلش. بیشتر این باگها رو موقع نوشتن همین راهنما و تست کردن کتابخونهها از نزدیک دیدیم و بازتولید کردیم!
۱. محاسبات تقویم
پیوند به بخش ۱. محاسبات تقویم| # | خطا / باگ | چطوری خودش رو نشون میده؟ | راهحل درست |
|---|---|---|---|
| ۱ | استفاده از الگوریتم چرخهٔ ۲۸۲۰ ساله (بیرشک) | تمام تاریخهای بین ۲۰ مارس ۲۰۲۵ تا ۲۰ مارس ۲۰۲۶ (کل سال ۱۴۰۴) یک روز جابهجا میشن و ۳۰ اسفند ۱۴۰۳ اصلا وجود نداره! | استفاده از فرمول ۳۳ ساله + جدول اصلاح، یا یکی از کتابخونههای تیکخورده (✅) در بخش ۶ |
| ۲ | فرض کردن اینکه کبیسهها همیشه ۴ سال یکبارن (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) |
۵. دیتابیس و طراحی API
پیوند به بخش ۵. دیتابیس و طراحی API| # | خطا / باگ | چطوری خودش رو نشون میده؟ | راهحل درست |
|---|---|---|---|
| ۳۰ | ذخیره کردن تاریخ فقط به صورت رشتهٔ متنی شمسی در دیتابیس | کوئری زدن سخت میشه، توابع تاریخ دیتابیس از کار میافتن و مرتبسازی باگ میخوره | ذخیره کردن به صورت تاریخ استاندارد میلادی (date / timestamptz) و تبدیل به شمسی در لایهٔ نمایش |
| ۳۱ | گذاشتن تاریخ شمسی داخل فیلد استاندارد ISO 8601 در API | کلاینتها و کتابخونهها رشتهٔ 1404-01-01 رو سال ۱۴۰۴ میلادی (قرن پانزدهم!) تفسیر میکنن |
ارسال تاریخ میلادی در فیلد اصلی و گذاشتن تاریخ شمسی در فیلد جداگانه مثل date_fa |
| ۳۲ | هاردکد کردن تعطیلات رسمی داخل کد برنامه | با اولین تغییر قانون یا جابهجا شدن ماههای قمری، تعطیلات برنامه اشتباه میشه | خوندن تعطیلات از روی فایل/سرویس دادهٔ قابل آپدیت |
| ۳۳ | استفاده از تقویمهای islamic یا islamic-umalqura برای تعطیلات قمری ایران |
تعطیلاتی مثل عید فطر یا عاشورا در بعضی سالها یک روز خطا دارن | استفاده از جدول شروع ماههای قمری ایران (بخش ۷: تعطیلات) |