عداد أسطر تعليقات الشفرة
قِس كم من ملف الشفرة يشرح بدل أن ينفّذ: مقطع من ستة أسطر فيه ثلاثة أسطر تعليقات وثلاثة أسطر شفرة يعطي نسبة 1 وتعليقات بنسبة 50 بالمئة. علامات التعليق داخل علامات الاقتباس لا تُحتسب. مجانية في متصفحك.
- مجاني
- يعمل في متصفحك
- دون تسجيل
- بياناتك لا تغادر جهازك
شغّل الأداة مجانًا
مثال محلول
- اللغة
- Javascript
- إجمالي الأسطر
- 6
- الأسطر الفارغة
- 1
- أسطر التعليقات
- 3
- أسطر الشيفرة
- 3
يقيس عداد أسطر التعليقات مقدار ما يخصصه الملف المصدري للشرح بدلًا من الشفرة القابلة للتنفيذ. الصقوا النص المصدري، واختاروا اللغة أو استخدموا الكشف التلقائي، لتحصلوا على أعداد أسطر التعليقات والشفرة والأسطر الفارغة والمختلطة، إلى جانب نسبة التعليقات إلى الشفرة. تمثل النتيجة مؤشرًا موجزًا لكثافة التوثيق يفيد في مراجعة الشفرة وتخطيط الصيانة ولوحات الجودة وتدقيق المستودعات. يعمل المسح المعجمي بصورة حتمية، ولا يعد علامات التعليق داخل السلاسل النصية، ويعرض اللغة المختارة في كل استجابة.
اقرؤوا المقياس دون تحويله إلى هدف ثابت
تفيد كثافة التعليقات عندما تبدأ نقاشًا، لا عندما تصبح درجة عامة ملزمة. يقسم هذا العداد عدد أسطر التعليقات على عدد أسطر الشفرة، ويعرض التعليقات أيضًا كنسبة مئوية من مجموع مشاهدات التعليقات والشفرة. ينتمي السطر الذي يجمع شفرة وتعليقًا لاحقًا إلى الفئتين، ويكشف عداد الأسطر المختلطة هذا التداخل بوضوح.
أما الأسطر الفارغة فلا تدخل في أي منهما. تجعل هذه التعريفات القياسات المتكررة قابلة للمقارنة، لكنها لا تزعم أن كثرة التعليقات تعني دائمًا برمجيات أفضل. قد تكون دالة تحليل صغيرة واضحة بأسمائها واختباراتها وحدها، بينما قد يحتاج تنفيذ بروتوكول إلى ملاحظات واسعة عن الثوابت والقيود الخارجية.
قارنوا ملفات متشابهة في الدور واللغة ومرحلة النضج. ابحثوا عن تغيرات لافتة، مثل اختفاء الشرح من نظام فرعي معقد، أو وجود ترويسات مضللة في شفرة مولدة، أو ارتفاع الكثافة بسبب شفرة معطلة تركت داخل التعليقات. اجمعوا النتيجة مع التعقيد وتغطية الاختبارات وتكرار التعديلات والحكم المهني.
يدل المقياس على المواضع الجديرة بالقراءة، لكنه لا يحكم على صحة التعليق أو ضرورته أو فائدته.
اختاروا اللغة وافهموا قواعد العد
اختاروا لغة المصدر متى كانت معروفة، لأن علامات التعليقات تختلف بين اللغات. تستخدم لغات عائلة C شرطتين مائلتين لتعليق السطر وكتلًا بين الشرطة المائلة والنجمة؛ وتستخدم Python وبرامج shell علامة الشباك؛ وتجمع SQL بين شرطتين وكتل التعليقات، بينما تستخدم HTML محددات خاصة بالترميز. يفحص الوضع التلقائي أنماط المصدر الشائعة ويعيد اللغة المستنتجة، وبذلك يظل القرار ظاهرًا.
يتابع الماسح كتل التعليقات عبر عدة أسطر فعلية، ويتجاهل العلامات الظاهرية داخل السلاسل المحاطة بعلامات اقتباس مفردة أو مزدوجة أو خلفية. يصنف كل سطر فعلي بحسب احتوائه على شفرة أو تعليق أو كليهما أو لا شيء منهما. لذلك تضيف الكتلة متعددة الأسطر سطر تعليق عن كل سطر فعلي تشغله.
ويزيد التعليق اللاحق لتعليمة أعداد الشفرة والتعليقات والأسطر المختلطة معًا. هذا النهج المعجمي سريع وحتمي، لكنه ليس مترجمًا برمجيًا كاملًا. قد تتطلب السلاسل الخام غير المعتادة واللغات المضمنة وحيل المعالج القبلي وحروف التوثيق الخاصة بلغة معينة اختيارًا صريحًا للغة أو محللًا متخصصًا عندما يكون التصنيف الدلالي الدقيق ضروريًا.
استخدموا النتيجة في المراجعات وفحوص الصيانة
في المراجعة الفردية، شغلوا العداد قبل التغيير وبعده وافحصوا التحولات الكبيرة بدلًا من فرض حد ثابت. قد يشير انخفاض النسبة في خوارزمية ازدادت تعقيدًا إلى أن الافتراضات أو الحالات الحدية تحتاج إلى شرح. وقد تعكس زيادة النسبة توثيقًا جيدًا، لكنها قد تكشف أيضًا شفرة معلقة ينبغي حذفها وحفظها في نظام التحكم بالإصدارات.
على مستوى المستودع، خزّنوا الأعداد مع معرف commit واللغة ومسار الملف وحالة كونه مولدًا. اجمعوا النتائج ضمن مجموعات قابلة للمقارنة فقط، لأن ملفات الإعداد والاختبارات والعملاء المولدين ومنطق التطبيق تختلف في حاجتها إلى التوثيق. تعاملوا مع الرقم كدليل لترتيب الأولويات: ادمجوه مع تكرار التغييرات لاكتشاف الملفات كثيرة التعديل وقليلة الشرح، أو مع التعقيد لتوجيه انتباه المراجعين.
واقرؤوا التعليقات الفعلية دائمًا قبل استنتاج أي حكم بشأن قابلية الصيانة.
حالات الاستخدام
مراجعة تغييرات التوثيق
قارنوا الكثافة قبل التعديل وبعده، وافحصوا التحولات غير المتوقعة في الملفات المعقدة.
إنشاء لوحة لمؤشرات الجودة
سجلوا الأعداد والنسب المستقرة إلى جانب التعقيد والتغييرات وتغطية الاختبارات.
ترتيب أولويات الصيانة
حددوا الوحدات كثيرة التغيير التي توفر قدرًا ضئيلًا جدًا من السياق التفسيري.
الأسئلة الشائعة
ما نسبة التعليقات إلى الشفرة؟
هي عدد أسطر التعليقات مقسومًا على عدد أسطر الشفرة، مع تقريب النتيجة إلى ست منازل عشرية.
كيف تحسبون السطر الذي يجمع شفرة وتعليقًا؟
يحسب مرة ضمن الشفرة، ومرة ضمن التعليقات، ومرة في الحقل المنفصل للأسطر المختلطة.
هل تؤثر الأسطر الفارغة في النسبة؟
لا. تعرض منفصلة وتستبعد من حدي النسبة كليهما.
ماذا يحدث إذا احتوى الملف على تعليقات دون شفرة؟
يحذف حقل النسبة لأن القسمة على صفر لا تنتج قيمة منتهية، بينما تظل الأعداد الفردية متاحة.
هل الكشف التلقائي عن اللغة دقيق دائمًا؟
لا. يستخدم قواعد أنماط متحفظة ويعرض اختياره. اختاروا اللغة صراحة عندما تكون الدقة ضرورية.
هل تقيم الأداة جودة التعليقات؟
لا. تقيس كثافة الأسطر الفعلية، ولا تحكم على صحة التعليقات أو حداثتها أو فائدتها.
أدوات ذات صلة
للمطوّرين — الوصول عبر API
كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.
الـEndpoint
صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.
استدعِ الخدمة من بيئتك
curl -X POST https://api.kit.forhosting.com/dev/count-comments \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"// Convert a value\nfunction double(value) {\n return value * 2; // arithmetic\n}"}'const res = await fetch("https://api.kit.forhosting.com/dev/count-comments", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "// Convert a value\nfunction double(value) {\n return value * 2; // arithmetic\n}"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/count-comments",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"text": "// Convert a value\nfunction double(value) {\n return value * 2; // arithmetic\n}"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/count-comments", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"text":"// Convert a value\\nfunction double(value) {\\n return value * 2; // arithmetic\\n}"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"text":"// Convert a value\nfunction double(value) {\n return value * 2; // arithmetic\n}"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/count-comments", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)مثال على الطلب
{
"text": "// Convert a value\nfunction double(value) {\n return value * 2; // arithmetic\n}"
}مثال على الاستجابة
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.count_comments",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.
الأسعار
السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.
الحدود
max_mb | 5 |
الأخطاء
| HTTP | الرمز | المعنى |
|---|---|---|
401 | unauthorized | مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك. |
402 | insufficient_balance | رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة. |
404 | unknown_type | نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب. |
429 | rate_limited | تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة. |
ملاحظات تقنية
استخدموا النتيجة في المراجعات وفحوص الصيانة
يناسب خرج JSON المستقر لوحات الجودة وتقارير التكامل المستمر، بينما يتيح التشغيل في المتصفح فحصًا سريعًا وخاصًا. تبلغ كلفة التشغيل الآلي عبر API مقدار $0.002 لكل طلب.