فایل settings.json من در VS Code پر از یادداشت‌هایی است که برای خودم نوشته‌ام. یک خط توضیح می‌دهد چرا ذخیره‌سازی خودکار کمی درنگ می‌کند و خطی دیگر یادآوری می‌کند که چرا پوشه‌های ساخت پنهان شده‌اند. پس از دست‌کاری چند تنظیم VS Code که کدنویسی را روان‌تر می‌کنند، همین توضیحات‌اند که کمک می‌کنند دلیل وجود هر تنظیم را به یاد بیاورم.
اما اگر همین فایل را به تجزیه‌گر داخلی JSON در پایتون بدهید، به نخستین توضیح که می‌رسد از کار می‌افتد. این تفاوت عمدی است. VS Code از نسخهٔ ۱.۱۹ که در نوامبر ۲۰۱۷ منتشر شد، فایل‌های پیکربندی خودش را در حالتی جداگانه باز می‌کند که آگاهانه اجازهٔ نوشتن توضیحات را می‌دهد.
فایل تنظیمات شما بی‌سروصدا قواعد JSON را زیر پا می‌گذارد
توضیحات و ویرگول پایانی هرگز بخشی از استاندارد نبودند
JSON، کوتاه‌شدهٔ JavaScript Object Notation، قالبی متنی است که بی‌شمار برنامه و وب‌سایت برای جابه‌جایی داده به کار می‌برند. استاندارد رسمی آن، RFC ۸۲۵۹، استفاده از شیء، آرایه، رشته، عدد، true، false و null را مجاز می‌داند؛ اما نه توضیحات را می‌پذیرد و نه ویرگول پایانی را، یعنی همان ویرگول اضافه پس از آخرین مورد یک فهرست.
این حذف آگاهانه بود. داگلاس کراکفورد، سازندهٔ JSON، توضیح داده است که توضیحات را کنار گذاشت، چون افراد از آن‌ها برای نگهداری دستورهای تجزیه استفاده می‌کردند و این کار سازگاری میان سامانه‌ها را به خطر می‌انداخت.
بااین‌حال، فایل settings.json در پروژهٔ یادداشت‌های سریع من از هر دو مورد فراوان دارد: توضیحات تک‌خطی که با // آغاز می‌شوند، توضیحی چندخطی که میان /* */ قرار گرفته است و در دو جا نیز ویرگول‌هایی پس از آخرین مورد. VS Code هیچ مشکلی گزارش نمی‌کند. همین وضع دربارهٔ فایل‌های tasks.json، launch.json و tsconfig.json نیز برقرار است؛ فایل‌هایی که به احتمال زیاد آن‌ها را دستی ویرایش می‌کنید.
به‌گمانم این تصمیم درستی است. ممکن است ماه‌ها بعد دوباره به یک فایل پیکربندی سر بزنید و یادداشتی یک‌خطی که دلیل فعال‌کردن یک تنظیم را توضیح می‌دهد، نمی‌گذارد آن را اشتباهی خاموش کنید. JSON سخت‌گیرانه ناچارمان می‌کند این توضیحات را به سندی جداگانه منتقل کنیم که هیچ‌کس آن را باز نمی‌کند.
فایل‌های پیکربندی حالت اختصاصی JSONC دارند
نوار وضعیت میزان سخت‌گیری ویرایشگر را تعیین می‌کند
کلید تغییر حالت در گوشهٔ پایین سمت راست نوار وضعیت قرار دارد. اگر یک فایل معمولی با پسوند .json را باز کنید، نشانگر زبان عبارت JSON را نمایش می‌دهد. با بازکردن settings.json، این نشانگر عبارت «JSON همراه با توضیحات» را نشان می‌دهد که معمولاً به‌اختصار JSONC نامیده می‌شود. همین یک برچسب تعیین می‌کند ویرایشگر کدام قواعد را به اجرا بگذارد.
مایکروسافت این انتخاب را آگاهانه انجام داده است. طبق یادداشت‌های انتشار مایکروسافت برای VS Code ۱.۱۹، حالت تازه برای جداکردن فایل‌های شبیه JSON که توضیحات را می‌پذیرند از فایل‌های پیرو استاندارد افزوده شد. تجزیهٔ این فایل‌ها بر عهدهٔ node-jsonc-parser است؛ کتابخانه‌ای متن‌باز از مایکروسافت که در برابر بحث همیشگی دربارهٔ میزان متن‌بازبودن خود VS Code، تضاد جالبی پدید می‌آورد.
برای دیدن تفاوت، یک پیکربندی یکسان را دو بار ذخیره کردم: یک‌بار با نام app-config.json و بار دیگر با نام app-config.jsonc. نسخهٔ .json با چهار خطا روشن شد، اما نسخهٔ .jsonc هیچ خطایی و تنها دو هشدار زرد نشان داد. نکتهٔ جالب همین هشدارهاست. VS Code در یک فایل عمومی .jsonc، ویرگول‌های پایانی را مطابق مستندات خود ــ که استفاده از آن‌ها را نامطلوب می‌داند ــ به‌صورت هشدار علامت می‌زند. بااین‌حال، همین ویرگول‌ها در settings.json و tsconfig.json بی‌هیچ هشداری پذیرفته می‌شوند. VS Code این فایل‌ها را می‌شناسد و قواعد را برایشان باز هم آسان‌گیرانه‌تر می‌کند.
این سازشی منطقی است. در فایل‌های پیکربندی مدام خط‌ها را می‌افزایید، حذف می‌کنید یا جابه‌جا می‌کنید و یک ویرگول سرگردان پس از آخرین مورد، از علت‌های رایج بازنشدن فایل است. اگر یکی از فایل‌های خودتان در حالت سخت‌گیرانه مانده، در نوار وضعیت روی JSON کلیک کنید و گزینهٔ «JSON همراه با توضیحات» را برگزینید.
این رفتار را با VS Code ۱.۱۴۰ روی Windows ۱۱ آزمودم. برخورد با ویرگول‌های پایانی در فایل‌های گوناگون یکسان نیست؛ بنابراین به‌جای آنکه همهٔ فایل‌های JSONC را به یک اندازه آسان‌گیر بدانید، پنل «مشکلات» را بررسی کنید.
تجزیه‌گرهای سخت‌گیر از این توضیحات نمی‌گذرند
آسان‌گیری با خروج فایل از VS Code پایان می‌یابد
یک اسکریپت کوتاه پایتون را برای خواندن app-config.jsonc به کار گرفتم و از ماژول داخلی json استفاده کردم که از استاندارد رسمی پیروی می‌کند. اسکریپت بی‌درنگ در خط ۲، ستون ۳ ــ دقیقاً همان‌جایی که نخستین توضیح آغاز می‌شود ــ با خطای JSONDecodeError روبه‌رو شد. فرمان ConvertFrom-Json در Windows PowerShell نیز فایل را نپذیرفت.
همین دام درون VS Code نیز وجود دارد. فایل package.json که npm برای مدیریت پروژه‌های JavaScript می‌خواند، در حالت سخت‌گیرانهٔ JSON باقی می‌ماند؛ بنابراین حتی یک توضیح در آن با خطای قرمز روبه‌رو می‌شود. فهرست برنامه‌هایی که هنگام بازسازی محیط Windows با فرمان‌های برون‌بری و درون‌ریزی Winget به دست می‌آید نیز از JSON معمولی استفاده می‌کند.
طرفداران JSON سخت‌گیرانه در اینجا حق دارند. دیدگاه‌های توضیحی راه را برای گویش‌های گوناگون باز می‌کنند و JSONC، JSON5 و HJSON هرکدام قالب را به شیوه‌ای اندکی متفاوت تغییر می‌دهند؛ در نتیجه، فایلی که در یک ابزار کار می‌کند ممکن است در ابزار دیگری از کار بیفتد. بااین‌حال، VS Code استفاده از JSONC را به حالتی مشخص و مجموعه‌ای شناخته‌شده از فایل‌ها محدود می‌کند. فایل‌های داده‌تان همچنان از قواعد سخت‌گیرانه پیروی می‌کنند و نوار وضعیت نیز نشان می‌دهد کدام قواعد برقرارند.
در عمل، کافی است دو عادت داشته باشید: در فایل‌هایی که با عنوان «JSON همراه با توضیحات» مشخص شده‌اند آزادانه توضیح بنویسید، اما پیش از فرستادن فایل به اسکریپت، API یا برنامه‌ای دیگر، همه آن توضیحات را پاک کنید.
توضیحات را امتیاز ویژه فایل‌های پیکربندی بدانید
آزادانه توضیح بنویسید، اما نخست نوار وضعیت را ببینید
به نظر می‌رسد JSONC از آوازه‌اش به‌عنوان یکی از ویژگی‌های نامتعارف VS Code ماندگارتر باشد. پیش‌نویس یک استاندارد تدوین‌شده به دست جامعه از سپتامبر ۲۰۲۵ در دست تهیه است و این نشان می‌دهد که شاید ابزارهای دیگر نیز سرانجام بر سر همین قواعد به توافق برسند. تا آن زمان، بهتر است توضیح‌نویسی را امتیازی ویژه فایل‌های پیکربندی بدانیم. بنویسید چرا تنظیمی را تغییر داده‌اید، فایل‌های داده را سخت‌گیرانه نگه دارید و پیش از کپی‌کردن پیکربندی در جایی دیگر، نگاهی به حالت زبان بیندازید.
این قانون‌شکنی تنها به این دلیل جواب می‌دهد که آگاهانه و مهارشده است. وقتی فایل تنظیماتتان را هم مرتب کردید، افزونه‌های VS Code که بهتر است از همان آغاز نصب شوند مقصد بعدی مناسبی‌اند.
منبع: این مطلب ترجمه و بومی‌سازی مقاله‌ای از MakeUseOf به قلم Yasir Mahmood است. مشاهده مقاله اصلی