تعليق (برمجة حاسوبية)

في برمجة الكمبيوتر ، التعليق هو شرح أو تعليق يمكن للإنسان قراءته في الكود المصدر لبرنامج الكمبيوتر . تتم إضافتها بغرض جعل الكود المصدر أسهل للفهم من قبل البشر، وعادة ما يتم تجاهلها من قبل المترجمين والمفسرين . [ 1 ^{] [2]} يختلف بناء الجملة للتعليقات في لغات البرمجة المختلفة بشكل كبير.

تتم معالجة التعليقات أحيانًا أيضًا بطرق مختلفة لإنشاء وثائق خارجية لكود المصدر نفسه بواسطة مولدات الوثائق ، أو استخدامها للتكامل مع أنظمة إدارة كود المصدر وأنواع أخرى من أدوات البرمجة الخارجية .

إن المرونة التي توفرها التعليقات تسمح بدرجة كبيرة من التنوع، ولكن الاتفاقيات الرسمية لاستخدامها تشكل عادةً جزءًا من أدلة أسلوب البرمجة .

يتم تنسيق التعليقات بشكل عام إما كتعليقات كتلة (تسمى أيضًا تعليقات المقدمة أو تعليقات التدفق ) أو تعليقات السطر (تسمى أيضًا تعليقات مضمنة ). ^[3]

تحدد التعليقات الكتلية منطقة من الكود المصدري والتي قد تمتد على عدة أسطر أو جزء من سطر واحد. يتم تحديد هذه المنطقة بفاصل بداية وفاصل نهاية . تسمح بعض لغات البرمجة (مثل MATLAB ) بتداخل التعليقات الكتلية بشكل متكرر داخل بعضها البعض، لكن لغات أخرى (مثل Java ) لا تسمح بذلك. ^{[4] [5] [6]}

تبدأ تعليقات السطر إما بفاصل تعليق وتستمر حتى نهاية السطر، أو في بعض الحالات، تبدأ عند عمود معين (إزاحة سطر الحرف) في الكود المصدر، وتستمر حتى نهاية السطر. ^[6]

تستخدم بعض لغات البرمجة التعليقات الكتلية والتعليقات السطرية مع فواصل تعليق مختلفة. على سبيل المثال، تحتوي لغة C++/* على تعليقات كتلية محددة بـ و */والتي يمكن أن تمتد إلى عدة أسطر وتعليقات سطر محددة بـ //. تدعم لغات أخرى نوعًا واحدًا فقط من التعليقات. على سبيل المثال، تعليقات Ada هي تعليقات سطرية: تبدأ بـ --وتستمر حتى نهاية السطر. ^[6]

إن أفضل طريقة للاستفادة من التعليقات هي محل نزاع؛ فقد قدم العديد من المعلقين وجهات نظر متنوعة ومتعارضة في بعض الأحيان. ^{[7] [8]} هناك العديد من الطرق المختلفة لكتابة التعليقات والعديد من المعلقين يقدمون نصائح متضاربة. ^[8]

يمكن استخدام التعليقات كشكل من أشكال الكود الزائف لتحديد النية قبل كتابة الكود الفعلي. في هذه الحالة، يجب أن تشرح التعليقات المنطق وراء الكود وليس الكود نفسه.

/* تكرار للخلف عبر جميع العناصر التي أعادها الخادم 
(يجب معالجتها بترتيب زمني)*/ 
for ( i = ( numElementsReturned - 0 ); i >= 1 ; i -- ) { /* معالجة بيانات كل عنصر */ updatePattern ( i , returnsElements [ i ]); }          
    
     

إذا تم ترك هذا النوع من التعليقات، فإنه يبسط عملية المراجعة من خلال السماح بالمقارنة المباشرة بين الكود والنتائج المقصودة. من المغالطات المنطقية الشائعة أن الكود الذي يسهل فهمه يقوم بما يفترض أن يقوم به.

يمكن استخدام التعليقات لتلخيص الكود أو لشرح قصد المبرمج. وفقًا لهذه المدرسة الفكرية، فإن إعادة صياغة الكود باللغة الإنجليزية البسيطة تعتبر غير ضرورية؛ قد تكون الحاجة إلى إعادة شرح الكود علامة على أنه معقد للغاية ويجب إعادة كتابته، أو أن التسمية سيئة.

"لا توثق الكود السيئ - قم بإعادة كتابته." ^[9]

"لا تكرر التعليقات الجيدة الكود أو تشرحه. بل إنها توضح الغرض منه. يجب أن تشرح التعليقات، على مستوى تجريد أعلى من الكود، ما تحاول القيام به." ^[10]

يمكن أيضًا استخدام التعليقات لشرح سبب عدم توافق كتلة من التعليمات البرمجية مع الأعراف أو أفضل الممارسات. وينطبق هذا بشكل خاص على المشاريع التي لا تتطلب سوى وقت قليل جدًا للتطوير، أو في إصلاح الأخطاء. على سبيل المثال:

'المتغير الثاني dim بسبب أخطاء الخادم الناتجة عند إعادة استخدام بيانات النموذج. لا توجد 
وثائق متاحة حول مشكلة سلوك الخادم، لذا فقط الترميز حولها. 
vtx = server . mappath ( "local settings" )  

في بعض الأحيان، يحتوي الكود المصدر على حل جديد أو جدير بالملاحظة لمشكلة معينة. في مثل هذه الحالات، قد تحتوي التعليقات على شرح للمنهجية. قد تتضمن هذه التفسيرات مخططات وإثباتات رياضية رسمية. قد يشكل هذا شرحًا للكود، بدلاً من توضيح غرضه؛ ولكن قد يجد الآخرون المكلفون بصيانة قاعدة الكود مثل هذا التفسير أمرًا بالغ الأهمية. قد يكون هذا صحيحًا بشكل خاص في حالة مجالات المشكلات المتخصصة للغاية؛ أو التحسينات أو الإنشاءات أو استدعاءات الوظائف التي نادرًا ما تستخدم. ^[11]

على سبيل المثال، قد يضيف المبرمج تعليقًا لشرح سبب اختيار الفرز بالإدراج بدلاً من الفرز السريع ، حيث أن الأول أبطأ نظريًا من الثاني. يمكن كتابة هذا على النحو التالي:

 list = [ f ( b ), f ( b ), f ( c ), f ( d ), f ( a ), ... ] ; // نحتاج إلى فرز مستقر. بالإضافة إلى ذلك، فإن الأداء لا يهم حقًا. insertion_sort ( list );            
 
  

يمكن إدراج الشعارات والرسوم البيانية ومخططات التدفق المكونة من هياكل فنية بتنسيق ASCII في الكود المصدر بتنسيق تعليق. ^[12] علاوة على ذلك، يمكن تضمين إشعارات حقوق النشر داخل الكود المصدر كتعليقات. يمكن أيضًا ترميز البيانات الثنائية في التعليقات من خلال عملية تُعرف باسم الترميز الثنائي إلى نص ، على الرغم من أن هذه الممارسة غير شائعة وعادةً ما يتم تخصيصها لملفات الموارد الخارجية.

الجزء التالي من التعليمات البرمجية عبارة عن رسم تخطيطي بسيط بتنسيق ASCII يصور تدفق العملية لبرنامج نصي لإدارة النظام موجود في ملف نصي يعمل بنظام Windows Script Host . ورغم أن القسم الذي يشير إلى التعليمات البرمجية يظهر كتعليق، فإن الرسم التخطيطي نفسه يظهر في الواقع في قسم XML CDATA ، والذي يعتبر من الناحية الفنية مختلفًا عن التعليقات، ولكنه يمكن أن يخدم أغراضًا مماثلة. ^[13]

<!-- begin: wsf_resource_nodes --> 
<resource id= "ProcessDiagram000" > <![CDATA[ HostApp (Main_process)     |     V script.wsf (app_cmd) --> ClientApp (async_run, batch_process)                 |                 |                 V          mru.ini (mru_history)   ]]> </resource> 

على الرغم من أنه كان من الممكن بسهولة تضمين هذا الرسم التخطيطي المتطابق كتعليق، إلا أن المثال يوضح حالة واحدة حيث قد يختار المبرمج عدم استخدام التعليقات كطريقة لتضمين الموارد في الكود المصدر. ^[13]

غالبًا ما تقوم التعليقات الموجودة في برنامج الكمبيوتر بتخزين بيانات وصفية حول ملف البرنامج.

على وجه الخصوص، يقوم العديد من مطوري البرامج بوضع إرشادات الإرسال في التعليقات لمساعدة الأشخاص الذين يقرؤون الكود المصدر لهذا البرنامج على إرسال أي تحسينات يقومون بها إلى المطور.

تتضمن البيانات الوصفية الأخرى: اسم منشئ الإصدار الأصلي لملف البرنامج وتاريخ إنشاء الإصدار الأول، واسم المشرف الحالي على البرنامج، وأسماء الأشخاص الآخرين الذين قاموا بتحرير ملف البرنامج حتى الآن، وعنوان URL للوثائق حول كيفية استخدام البرنامج، واسم ترخيص البرنامج لملف البرنامج هذا، وما إلى ذلك.

عندما تعتمد خوارزمية في بعض أقسام البرنامج على وصف في كتاب أو مرجع آخر، يمكن استخدام التعليقات لإعطاء رقم الصفحة وعنوان الكتاب أو طلب التعليقات أو مرجع آخر.

من الممارسات الشائعة لدى المطورين التعليق على مقتطف من التعليمات البرمجية، أي إضافة صيغة تعليق تجعل كتلة التعليمات البرمجية تلك تصبح تعليقًا، بحيث لا يتم تنفيذها في البرنامج النهائي. يمكن القيام بذلك لاستبعاد أجزاء معينة من التعليمات البرمجية من البرنامج النهائي، أو (الأكثر شيوعًا) يمكن استخدامها للعثور على مصدر الخطأ. من خلال التعليق بشكل منهجي وتشغيل أجزاء من البرنامج، يمكن تحديد مصدر الخطأ، مما يسمح بتصحيحه.

تسمح العديد من بيئات التطوير المتكاملة بإضافة أو إزالة مثل هذه التعليقات بسرعة باستخدام خيارات قائمة واحدة أو مجموعات مفاتيح. كل ما على المبرمج فعله هو تحديد جزء النص الذي يريد (أو إزالة) التعليق عليه واختيار الخيار المناسب.

تخزن أدوات البرمجة أحيانًا الوثائق والبيانات الوصفية في التعليقات. ^[14] قد تتضمن هذه مواضع الإدراج لإدراج ملف الرأس تلقائيًا، أو أوامر لتعيين وضع تمييز بناء الجملة للملف ، ^{[15] أو} رقم مراجعة الملف . ^[16] يُشار إلى تعليقات التحكم الوظيفية هذه أيضًا باسم التعليقات التوضيحية . يُعتبر الاحتفاظ بالوثائق داخل تعليقات التعليمات البرمجية المصدرية إحدى الطرق لتبسيط عملية التوثيق، فضلاً عن زيادة فرص تحديث الوثائق بالتغييرات في التعليمات البرمجية. ^[17]

تتضمن أمثلة مولدات الوثائق برامج Javadoc للاستخدام مع Java ، وDdoc لـ D ، وDoxygen لـ C ، وC++ ، وJava، و IDL ، و Visual Expert لـ PL/SQL ، وTransact-SQL ، و PowerBuilder ، و PHPDoc لـ PHP . تدعم Python و Lisp و Elixir و Clojure أشكال سلسلة الوثائق . ^[18]

تطبق لغات C# و F# و Visual Basic .NET ميزة مشابهة تسمى "تعليقات XML" والتي يتم قراءتها بواسطة IntelliSense من تجميع .NET المجمّع . ^[19]

في بعض الأحيان، يتم إعادة استخدام عناصر بناء الجملة التي كانت مخصصة في الأصل لتكون تعليقات لنقل معلومات إضافية إلى البرنامج، مثل " التعليقات الشرطية ". قد تكون مثل هذه "التعليقات الساخنة" هي الحل العملي الوحيد الذي يحافظ على التوافق مع الإصدارات السابقة، ولكن يُنظر إليها على نطاق واسع على أنها حل مؤقت . ^[20]

من الأمثلة المحددة على ذلك كتل المستندات ، وهي عبارة عن تعليقات بتنسيق خاص تُستخدم لتوثيق جزء معين من التعليمات البرمجية. وهذا يجعل تنسيق كتلة المستندات مستقلاً عن اللغة المستهدفة (طالما أنه يدعم التعليقات)؛ ومع ذلك، فقد يؤدي هذا أيضًا إلى معايير متعددة أو غير متسقة.

هناك حالات يتم فيها استغلال أحرف التعليق العادية لإنشاء توجيه خاص لمحرر أو مترجم.

ومن الأمثلة على هذا التوجيه للمترجم:

• " Shebang " Unix #!- يستخدم في السطر الأول من البرنامج النصي للإشارة إلى المترجم الذي يجب استخدامه.
• "التعليقات السحرية" التي تحدد الترميز الذي يستخدمه ملف المصدر، ^[21] على سبيل المثال، PEP 263 في Python. ^[22]

يُظهر البرنامج النصي أدناه لنظام يشبه يونكس كلا من هذه الاستخدامات:

#!/usr/bin/env python3 
# -*- الترميز: UTF-8 -*- 
الطباعة ( "اختبار" )

يشبه إلى حد ما استخدام التعليقات في C للتواصل مع المترجم بأن "السقوط" الافتراضي في بيان الحالة تم عمدًا:

التبديل ( الأمر ) {  
    حالة CMD_SHOW_HELP_AND_EXIT : 
      do_show_help ();
      /* السقوط من خلال */
    الحالة CMD_EXIT : 
      do_exit ();
      استراحة ؛
    الحالة CMD_OTHER : 
      افعل_الآخر ();
      استراحة ؛
    /* ... إلخ. ... */
  }

كان إدراج مثل هذا /* Fall thru */التعليق للقراء البشر اتفاقية شائعة بالفعل، ولكن في عام 2017 بدأ مُجمِّع gcc في البحث عن هذه التعليقات (أو غيرها من مؤشرات القصد المتعمد)، وإذا لم يتم العثور عليها، فإنه يصدر: "تحذير: قد يفشل هذا البيان". ^[23]

ستقوم العديد من برامج التحرير وبيئات التطوير المتكاملة بقراءة التعليقات ذات التنسيق الخاص. على سبيل المثال، ميزة "modelline" في Vim ؛ والتي من شأنها تغيير طريقة تعاملها مع علامات التبويب أثناء تحرير مصدر ما مع تضمين هذا التعليق بالقرب من أعلى الملف:

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

في بعض الأحيان، يقوم المبرمجون بإضافة تعليقات كوسيلة لتخفيف التوتر من خلال التعليق على أدوات التطوير، أو المنافسين، أو أصحاب العمل، أو ظروف العمل، أو جودة الكود نفسه. ^[24] يمكن ملاحظة حدوث هذه الظاهرة بسهولة من الموارد عبر الإنترنت التي تتعقب الألفاظ البذيئة في الكود المصدر. ^[25]

توجد وجهات نظر معيارية مختلفة وآراء راسخة منذ فترة طويلة فيما يتعلق بالاستخدام الصحيح للتعليقات في الكود المصدر. ^{[26] [27]} بعضها غير رسمي ويعتمد على التفضيل الشخصي، بينما يتم نشر أو إصدار البعض الآخر كإرشادات رسمية لمجتمع معين. ^[28]

لدى الخبراء وجهات نظر مختلفة حول ما إذا كانت التعليقات مناسبة في الكود المصدر، ومتى تكون كذلك. ^{[9] [29]} يؤكد البعض أن الكود المصدر يجب أن يُكتب مع القليل من التعليقات، على أساس أن الكود المصدر يجب أن يكون واضحًا بذاته أو موثقًا بذاته . ^[9] يقترح آخرون أن الكود يجب أن يكون مُعلقًا عليه على نطاق واسع (ليس من غير المألوف أن يكون أكثر من 50٪ من الأحرف غير المسافات البيضاء في الكود المصدري موجودة داخل التعليقات). ^{[30] [31]}

بين هذه الآراء هناك تأكيد على أن التعليقات ليست مفيدة ولا ضارة في حد ذاتها، وأن ما يهم هو أن تكون صحيحة ومتزامنة مع الكود المصدر، ويتم حذفها إذا كانت غير ضرورية أو مفرطة أو يصعب صيانتها أو غير مفيدة بأي شكل آخر. ^{[32] [33]}

يتم استخدام التعليقات في بعض الأحيان لتوثيق العقود في نهج التصميم حسب العقد في البرمجة.

اعتمادًا على الجمهور المستهدف من الكود واعتبارات أخرى، قد يختلف مستوى التفاصيل والوصف بشكل كبير.

على سبيل المثال، سيكون التعليق التالي في Java مناسبًا في نص تمهيدي مصمم لتعليم البرمجة المبتدئة:

سلسلة s = "Wikipedia" ؛ /* تعيين القيمة "Wikipedia" للمتغير s. */    

ومع ذلك، فإن هذا المستوى من التفصيل لن يكون مناسبًا في سياق الكود الإنتاجي، أو المواقف الأخرى التي تنطوي على مطورين ذوي خبرة. مثل هذه الأوصاف الأولية تتعارض مع المبدأ التوجيهي: "التعليقات الجيدة ... توضح النية". ^[10] علاوة على ذلك، بالنسبة لبيئات الترميز الاحترافية، يتم تحديد مستوى التفصيل بشكل جيد عادةً لتلبية متطلب أداء محدد تحدده العمليات التجارية. ^[31]

هناك العديد من البدائل الأسلوبية المتاحة عند التفكير في كيفية ظهور التعليقات في الكود المصدر. بالنسبة للمشاريع الأكبر التي تتضمن فريقًا من المطورين، يتم الاتفاق على أنماط التعليقات قبل بدء المشروع، أو تتطور كمسألة اتفاقية أو حاجة مع نمو المشروع. عادةً ما يفضل المبرمجون الأنماط المتسقة وغير المعوقة وسهلة التعديل ويصعب كسرها. ^[34]

إن أجزاء التعليمات البرمجية التالية في لغة C تمثل مجرد مثال صغير لكيفية اختلاف التعليقات من الناحية الأسلوبية، مع الاستمرار في نقل نفس المعلومات الأساسية:

/* 
     هذا هو نص التعليق. 
     الاختلاف الأول. 
*/

/***************************\ 
* * 
* هذا هو نص التعليق. 
* 
* * 
\****************************/

تميل عوامل مثل التفضيل الشخصي ومرونة أدوات البرمجة وغيرها من الاعتبارات إلى التأثير على المتغيرات الأسلوبية المستخدمة في الكود المصدر. على سبيل المثال، قد لا يكون البديل الثاني مفضلاً بين المبرمجين الذين لا يمتلكون محرري الكود المصدري الذين يمكنهم أتمتة محاذاة النص ومظهره المرئي في التعليقات.

مستشار البرمجيات والمعلق التكنولوجي ألين هولوب ^[35] هو أحد الخبراء الذين يدعون إلى محاذاة الحواف اليسرى للتعليقات: ^[36]

 /* هذا هو الأسلوب الموصى به من قبل Holub للغة C وC++. 
  * تم توضيح ذلك في ''Enough Rope''، في القاعدة 29. 
  */

 /* هذه طريقة أخرى للقيام بذلك، أيضًا في C. 
** من الأسهل القيام بذلك في المحررين الذين لا يقومون تلقائيًا بوضع مسافة بادئة للأسطر الثانية 
** خلال الأسطر الأخيرة من التعليق بمسافة واحدة من الأسطر الأولى. 
** يتم استخدامها أيضًا في كتاب Holub، في القاعدة 31. 
*/

تم توريث استخدام /* و */ كفاصلات لتعليقات الكتل من PL/I إلى لغة البرمجة B، السلف المباشر للغة البرمجة C. ^[37]

تستخدم تعليقات السطر بشكل عام فاصلًا عشوائيًا أو سلسلة من الرموز للإشارة إلى بداية التعليق، وحرف سطر جديد للإشارة إلى نهاية التعليق.

في هذا المثال، سيتم تجاهل كل النص من الأحرف ASCII // إلى نهاية السطر.

// ------------------------- 
// هذا هو نص التعليق. 
// -------------------------

غالبًا ما يتعين على مثل هذا التعليق أن يبدأ من أقصى اليسار ويمتد إلى السطر بالكامل. ومع ذلك، في العديد من اللغات، من الممكن أيضًا وضع تعليق مضمنًا في سطر الأوامر، لإضافة تعليق إليه - كما في مثال Perl هذا:

طباعة $s . "\n" ; # إضافة حرف سطر جديد بعد الطباعة        

إذا كانت اللغة تسمح بكل من تعليقات السطر وتعليقات الكتلة، فقد تقرر فرق البرمجة استخدامهما بشكل مختلف: على سبيل المثال، تعليقات السطر فقط للتعليقات البسيطة، وتعليقات الكتلة لوصف التجريدات ذات المستوى الأعلى.

قد يستخدم المبرمجون علامات غير رسمية في التعليقات للمساعدة في فهرسة المشكلات الشائعة. وقد يكون من الممكن البحث عنها باستخدام أدوات البرمجة الشائعة، مثل أداة grep في نظام التشغيل Unix أو حتى تمييزها من خلال بناء الجملة داخل محررات النصوص . يشار إليها أحيانًا باسم "علامات الكود" ^{[38] [39]} أو "الرموز"، وقد تساعدك أدوات التطوير حتى في سردها جميعًا. ^[40]

تختلف هذه العلامات على نطاق واسع، ولكنها قد تتضمن:

• خطأ، تصحيح الأخطاء — خطأ معروف يجب تصحيحه.
• FIXME — ينبغي تصحيحه.
• HACK، BODGE، KLUDGE — الحل البديل.
• TODO - شيء يجب القيام به.
• ملحوظة - تستخدم لتسليط الضوء على الأخطاء الملحوظة بشكل خاص .
• UNDONE — عكس أو "تراجع" عن الكود السابق.
• XXX - تحذير المبرمجين الآخرين من الكود الإشكالي أو المضلل

تختلف الأعراف الطباعية المستخدمة في تحديد التعليقات بشكل كبير. علاوة على ذلك، توفر لغات البرمجة الفردية أحيانًا متغيرات فريدة.

تستخدم لغة البرمجة Ada علامة '--' للإشارة إلى التعليق حتى نهاية السطر.

على سبيل المثال:

  -- تتلقى مهمة مراقب الحركة الجوية طلبات للإقلاع والهبوط 
   نوع المهمة  Controller ( My_Runway : Runway_Access ) هو -- إدخالات المهمة لتمرير الرسائل المتزامنة entry Request_Takeoff ( ID : in Airplane_ID ; Takeoff : out Runway_Access ); entry Request_Approach ( ID : in Airplane_ID ; Approach : out Runway_Access ); end Controller ;   
      
           
          
    

يستخدم APL⍝ للإشارة إلى تعليق يصل إلى نهاية السطر.

على سبيل المثال:

⍝ الآن أضف الأرقام: 
ج ← أ + ب ⍝ الجمع 

في اللهجات التي تحتوي على البدائيات ⊣("يسار") و ⊢("يمين")، يمكن أن تكون التعليقات غالبًا داخل عبارات أو عبارات منفصلة، ​​في شكل سلاسل متجاهلة:

د ← 2 × ج ⊣ 'حيث' ⊢ ج ← أ + 'حد' ⊢ ب    

يعرض هذا القسم من كود AppleScript النمطين للتعليقات المستخدمين في هذه اللغة.

(* 
يعرض هذا البرنامج تحية. 
*) 
عند  عرض التحية ( myGreeting ) 
     يتم عرض مربع حوار  myGreeting  &  "world!" 
end  greeting

-- إظهار التحية 
( " مرحبا" )

في هذا الجزء الكلاسيكي المبكر من كود BASIC، يتم استخدام الكلمة الأساسية REM ( "Remark" ) لإضافة التعليقات.

10 REM يوضح هذا البرنامج الأساسي استخدام عبارات PRINT وGOTO. 15 REM يملأ الشاشة بعبارة "HELLO" 20 PRINT "HELLO" 30 GOTO 20 
 
  
  

في إصدارات Microsoft BASIC اللاحقة، بما في ذلك Quick Basic ، وQ Basic ، و Visual Basic ، و Visual Basic .NET ، و VB Script ؛ وفي الإصدارات اللاحقة مثل FreeBASIC و Gambas، يتم أيضًا التعامل مع أي نص في السطر بعد حرف ' (علامة اقتباس أحادية) باعتباره تعليقًا.

مثال في Visual Basic .NET:

فئة عامة Form1 وفئة فرعية خاصة Button1_Click ( sender As Object و EventArgs ) تتعامل مع Button1 . انقر فوق الزر "يتم تنفيذ الكود التالي عندما ينقر المستخدم " على الزر في نافذة البرنامج. لا تزال تعليقات rem موجودة.  
             
        
        
        

        MessageBox . Show ( "Hello, World" ) 'إظهار نافذة منبثقة تحتوي على تحية End Sub End Class 
     
 

يوضح هذا المقطع من التعليمات البرمجية بلغة C استخدام تعليق تمهيدي أو "تعليق كتلة" لوصف غرض العبارة الشرطية . يشرح التعليق المصطلحات والمفاهيم الأساسية، ويتضمن توقيعًا قصيرًا للمبرمج الذي ألف التعليمات البرمجية.

 /* 
  * تحقق مما إذا كنا قد تجاوزنا الحد الأقصى للعمليات، ولكن تأكد من 
  استبعاد الجذر. هذا ضروري لتمكين تسجيل الدخول 
  والأصدقاء من تعيين حد العملية لكل مستخدم إلى شيء أقل 
  من عدد العمليات التي يقوم الجذر بتشغيلها. -- Rik 
  */ 
if ( atomic_read ( & p -> user -> processes ) >= p -> rlim [ RLIMIT_NPROC ]. rlim_cur && ! able ( CAP_SYS_ADMIN ) && ! able ( CAP_SYS_RESOURCE )) goto bad_fork_free ;    
        
      

منذ C99، أصبح من الممكن أيضًا استخدام بناء الجملة // من C++، مما يشير إلى تعليق مكون من سطر واحد.

يتيح توفر تعليقات الكتلة وضع علامة على الاختراقات الهيكلية، أي الانتهاكات المقبولة لقاعدة الدخول الفردي/الخروج الفردي في البرمجة المنظمة ، بشكل واضح، كما هو الحال في المثال التالي:

static Edge edge_any ( Node n , Node m ) { // يُرجع ما إذا كانت أي حافة تقع بين العقدتين $n و$m. Edge e ; for ( e = n -> borders ; e ; e = e -> next ) { if ( e -> dst == m ) { /*********/ return e ; } } for ( e = m -> borders ; e ; e = e -> next ) { if ( e -> dst == n ) { /*****/ break ; } } return e ; }      
    
     
        
            
    
        
            
       
      

في العديد من اللغات التي تفتقر إلى تعليق كتلة، مثل awk ، يمكنك استخدام تسلسلات من فواصل العبارات مثل ;بدلاً من ذلك. ولكن من المستحيل القيام بذلك في اللغات التي تستخدم المسافة البادئة كإشارة صارمة إلى بنية الكتلة المقصودة، مثل Python .

يمكن استخدام علامة التعجب ( ! ) لتمييز التعليقات في وضع تكوين جهاز توجيه Cisco، ومع ذلك لا يتم حفظ مثل هذه التعليقات في ذاكرة غير متطايرة (التي تحتوي على ملف تكوين بدء التشغيل)، ولا يتم عرضها بواسطة أمر "show run". ^{[41] [42]}

من الممكن إدراج محتوى يمكن قراءته بواسطة الإنسان وهو في الواقع جزء من التكوين، ويمكن حفظه في تكوين بدء تشغيل NVRAM عبر:

• الأمر "الوصف"، المستخدم لإضافة وصف إلى تكوين واجهة أو جار BGP
• معلمة "الاسم" لإضافة ملاحظة إلى مسار ثابت
• أمر "الملاحظة" في قوائم الوصول

!الصق النص أدناه لإعادة توجيه حركة المرور يدويًا
تكوين t
int gi0/2
لا اغلاق
مسار IP 0.0.0.0 0.0.0.0 gi0/2 اسم ISP2
لا يوجد مسار IP 0.0.0.0 0.0.0.0 gi0/1 اسم ISP1
int gi0/1
اغلق
مخرج

يستخدم ColdFusion تعليقات مشابهة لتعليقات HTML ، ولكن بدلاً من شرطتين، يستخدم ثلاث شرطات. يتم التقاط هذه التعليقات بواسطة محرك ColdFusion ولا يتم طباعتها في المتصفح.

مثل هذه التعليقات قابلة للتعشيش.

 <!--- يؤدي هذا إلى طباعة "Hello World" في المتصفح. 
   <!--- هذا تعليق مستخدم داخل التعليق الأول. 
   ---> 
---> 
 <cfoutput> 
   Hello World < br  /> 
 </cfoutput>

يستخدم D تعليقات بنمط C++، بالإضافة إلى تعليقات متعددة الأسطر بنمط D، والتي تبدأ بـ '/+' وتنتهي بـ '+/'.

// هذا تعليق مكون من سطر واحد. 
/* هذا تعليق مكون من عدة أسطر.

*/ 
/+ هذا هو 
  /+ تعليق متداخل +/ 
    +/

يوضح هذا المقطع من التعليمات البرمجية للغة Fortran IV كيفية استخدام التعليقات في هذه اللغة، والتي تعتمد بشكل كبير على الأعمدة. يؤدي الحرف "C" في العمود 1 إلى معاملة السطر بالكامل كتعليق.

C 
C الأسطر التي تبدأ بحرف "C" (في العمود الأول أو عمود "التعليق") هي تعليقات 
C 
WRITE ( 6 , 610 )   610 FORMAT ( 12 H HELLO WORLD ) END       
   
      

لاحظ أن أعمدة السطر يتم التعامل معها عادةً كأربعة حقول: الحقل من 1 إلى 5 هو حقل التسمية، والحقل 6 يتسبب في اعتبار السطر استمرارًا للبيان السابق؛ أما الإعلانات والبيانات فتذهب في الحقل من 7 إلى 72.

يوضح هذا الجزء من كود Fortran كيفية استخدام التعليقات في هذه اللغة، حيث تصف التعليقات نفسها قواعد التنسيق الأساسية.

! 
* * ...
​​​​​​​

       

تبدأ تعليقات الأسطر في Haskell بـ '--' (علامتي وصل) حتى نهاية السطر، وتبدأ تعليقات الأسطر المتعددة بـ '{-' وتنتهي بـ '-}'.

{- هذا تعليق 
على المزيد من الأسطر -} 
-- وهذا تعليق على سطر واحد 
putStrLn "Wikipedia" -- هذا تعليق آخر   

كما توفر لغة Haskell طريقة برمجة متعلمة للتعليق تُعرف باسم "Bird Style". ^[43] وفي هذه الطريقة يتم تفسير جميع الأسطر التي تبدأ بعلامة > على أنها كود، ويعتبر كل شيء آخر بمثابة تعليق. ومن المتطلبات الإضافية أن تترك دائمًا سطرًا فارغًا قبل وبعد كتلة الكود:

في نمط Bird، يجب عليك ترك مساحة فارغة قبل الكود.

> حقيقة :: عدد صحيح -> عدد صحيح > حقيقة 0 = 1 > حقيقة ( ن + 1 ) = ( ن + 1 ) * حقيقة ن    
   
      

ويجب عليك ترك سطر فارغ بعد الكود أيضًا.

يمكن أيضًا تنفيذ البرمجة المتقنة في Haskell باستخدام LaTeX . يمكن استخدام بيئة التعليمات البرمجية بدلاً من أسلوب Richard Bird: في أسلوب LaTeX ، يكون هذا معادلاً للمثال أعلاه، حيث يمكن تعريف بيئة التعليمات البرمجية في مقدمة LaTeX. فيما يلي تعريف بسيط:

\usepackage { حرفيًا } 
\newenvironment { الكود }{ \verbatim }{ \endverbatim }

في وقت لاحق

% ملف مصدر LaTeX تحسب مكالمة الدالة \verb 
| fact n| $ n ! $ إذا كان $ n \ge 0 $ ، فإليك التعريف: \\ \begin { code } fact :: Integer -> Integer fact 0 = 1 fact ( n + 1 ) = ( n + 1 ) * fact n \end { code } 
إليك المزيد من التوضيح باستخدام ترميز
 \LaTeX {} 

    
   
      

يعرض هذا الجزء من كود Java تعليقًا مطولًا يستخدم لوصف setToolTipTextالطريقة. يتوافق التنسيق مع معايير Sun Microsystems Javadoc . تم تصميم التعليق ليتم قراءته بواسطة معالج Javadoc.

/** 
* هذا تعليق كتلة في Java. 
* تسجل طريقة setToolTipText النص الذي سيتم عرضه في تلميح الأداة. 
* يتم عرض النص عندما يتوقف المؤشر فوق المكون. 
* 
* @param text السلسلة التي سيتم عرضها. إذا كان "text" فارغًا، 
* يتم إيقاف تشغيل تلميح الأداة لهذا المكون. 
*/ 
public void setToolTipText ( String text ) { // هذا تعليق مضمن في Java. TODO: كتابة التعليمات البرمجية لهذه الطريقة. }    
    

يستخدم JavaScript // لتسبق التعليقات و/* */ للتعليقات متعددة الأسطر.

// تعليق JavaScript بسطر واحد 
var iNum = 100 ; var iTwo = 2 ; // تعليق في نهاية السطر /* تعليق JavaScript متعدد الأسطر */   
    

تستخدم لغة برمجة Lua علامات الوصل المزدوجة، --، للتعليقات على سطر واحد بطريقة مشابهة للغات Ada و Eiffel و Haskell و SQL و VHDL . تحتوي Lua أيضًا على تعليقات كتلة، تبدأ بـ --[[وتستمر حتى إغلاق]]

على سبيل المثال:

--[[ تعليق طويل 
متعدد الأسطر ]] 
طباعة ( 20 )    -- طباعة النتيجة

إحدى التقنيات الشائعة للتعليق على جزء من التعليمات البرمجية، ^[44] هي وضع التعليمات البرمجية بين --[[و --]]، كما هو موضح أدناه:

--[[ 
print(10) 
--]] 
-- لا يوجد إجراء (تم التعليق عليه)

في هذه الحالة، من الممكن إعادة تنشيط الكود عن طريق إضافة شرطة واحدة إلى السطر الأول:

---[[ 
طباعة ( 10 ) 
--]] 
--> 10

في المثال الأول، --[[تبدأ علامة the في السطر الأول تعليقًا طويلًا، ولا تزال الواصلتان في السطر الأخير داخل هذا التعليق. في المثال الثاني، ---[[تبدأ السلسلة تعليقًا عاديًا من سطر واحد، بحيث يصبح السطر الأول والأخير تعليقين مستقلين. في هذه الحالة، printتكون علامة the خارج التعليقات. في هذه الحالة، يصبح السطر الأخير تعليقًا مستقلاً، حيث يبدأ بعلامة --.

يمكن أن تكون التعليقات الطويلة في Lua أكثر تعقيدًا من هذه، كما يمكنك القراءة في القسم المسمى "السلاسل الطويلة" راجع البرمجة في Lua .

في لغة برمجة MATLAB ، يشير الحرف '%' إلى تعليق من سطر واحد. تتوفر أيضًا تعليقات متعددة الأسطر عبر أقواس %{ و%} ويمكن تعشيشها، على سبيل المثال

% هذه هي المشتقات لكل حد 
d = [ 0 - 1 0 ]؛    

%{ 
  %{ ( 
مثال     على تعليق متداخل، المسافة البادئة مخصصة لمستحضرات التجميل (ويتم تجاهلها).) 
% } نقوم   بتكوين 
التسلسل ، باتباع صيغة تايلور . لاحظ أننا نعمل على متجه . % } seq = d . * ( x - c ) . ^ n ./ ( factorial ( n ) )         
        

       

% نضيف للحصول على تقريب تايلور 
approx = sum ( seq )  

يستخدم Nim علامة "#" للتعليقات المضمنة. يتم فتح تعليقات الكتل متعددة الأسطر باستخدام "#[" وإغلاقها باستخدام "]#". يمكن تضمين تعليقات الكتل متعددة الأسطر.

يحتوي Nim أيضًا على تعليقات توثيقية تستخدم ترميز Markdown و ReStructuredText المختلط . تستخدم تعليقات التوثيق المضمنة '##' ويتم فتح تعليقات توثيق الكتل متعددة الأسطر باستخدام '##[' وإغلاقها باستخدام ']##'. يمكن للمترجم إنشاء توثيق HTML و LaTeX و JSON من تعليقات التوثيق. تعليقات التوثيق هي جزء من شجرة بناء الجملة المجردة ويمكن استخراجها باستخدام وحدات الماكرو. ^[45]

## توثيق الوحدة *ReSTructuredText* و**MarkDown** 
# هذا تعليق، ولكنه ليس تعليق توثيق.

النوع Kitten = object ## توثيق النوع age : int ## توثيق الحقل     
     

proc purr ( self : Kitten ) = ## توثيق الدالة echo "Purr Purr" # هذا تعليق، ولكنه ليس تعليق توثيق.   
  
     

# هذا تعليق، ولكنه ليس تعليقًا على الوثائق.

يستخدم OCaml تعليقات قابلة للتضمين، وهو أمر مفيد عند التعليق على كتلة التعليمات البرمجية.

codeLine (* مستوى التعليق 1(* مستوى التعليق 2*)*)

في باسكال ودلفي ، يتم تحديد التعليقات بواسطة '{ ... }'. يمكن أن تبدأ أسطر التعليقات أيضًا بـ '\\'. كبديل، بالنسبة لأجهزة الكمبيوتر التي لا تدعم هذه الأحرف، يُسمح بـ '(* ... *)'. ^[46]

في عائلة اللغات الحديثة لنيكلاوس ويرث (بما في ذلك Modula-2 و Oberon )، يتم تحديد التعليقات بواسطة '(* ... *)'. ^{[47] [48]}

على سبيل المثال:

(* اختبار الأقطار *) 
columnDifference := testColumn - column ؛ إذا ( row + columnDifference = testRow ) أو .......    
      
    

يمكن تضمين التعليقات. // يمكن تضمينها في {} ويمكن تضمين {} في (**).

تبدأ تعليقات السطر في Perl ، والعديد من لغات البرمجة النصية الأخرى ، برمز التجزئة (#).

# مثال بسيط 
# 
my $s = "Wikipedia" ; # تعيين المتغير s إلى "Wikipedia". print $s . "\n" ; # إضافة حرف سطر جديد بعد الطباعة    
        

بدلاً من بناء التعليق الكتلي العادي، يستخدم Perl توثيقًا بسيطًا ، وهي لغة ترميز للبرمجة المتعلمة ، ^[49] على سبيل المثال: ^[50]

=item Pod::List-E<gt>new()

إنشاء كائن قائمة جديد. يمكن تحديد الخصائص من خلال 
مرجع تجزئة مثل هذا:

  قائمتي $list = Pod::List->new({ -start => $., -indent => 4 });

راجع الأساليب/الخصائص الفردية للحصول على التفاصيل.

=قطع

sub new { my $this = shift ؛ my $class = ref ( $this ) || $this ؛ my %params = @_ ؛ my $self = { %params }؛ bless $self ، $class ؛ $self -> initialize ()؛ return $self ؛ }  
       
         
       
       
      
    
     

يدعم R فقط التعليقات المضمنة التي تبدأ بعلامة التجزئة (#).

# هذا تعليق 
مطبوع ( "هذا ليس تعليقًا" ) # هذا تعليق آخر  

يستخدم Raku (الذي كان يسمى سابقًا Perl 6) نفس تعليقات الأسطر وتعليقات توثيق POD مثل Perl العادي (انظر قسم Perl أعلاه)، لكنه يضيف نوع تعليق كتلة قابل للتكوين: "تعليقات متعددة الأسطر / مضمنة". ^[51]

تبدأ هذه النصوص بعلامة تجزئة، تليها علامة عكسية، ثم بعض أحرف الأقواس الافتتاحية، وتنتهي بعلامة الأقواس الختامية المطابقة. ^[51] لا يمكن للمحتوى أن يمتد إلى عدة أسطر فحسب، بل يمكن أيضًا تضمينه في السطر.

#`{{ "التعليق على" هذا الإصدار 
toggle-case(Str:D $s)

تبديل حالة كل حرف في السلسلة:

  سلسلة $toggled-string = toggle-case("اسمي هو مايكل!");

}}

sub  toggle-case ( Str:D  $s ) #`(يتم استخدام هذا الإصدار من الأقواس الآن) {
    ...
}

يمكن أن تكون التعليقات في PHP إما بنمط C++ (سواء مضمنة أو كتلية)، أو تستخدم علامات التجزئة. PHPDoc هو نمط مقتبس من Javadoc وهو معيار شائع لتوثيق كود PHP.

بدءًا من PHP 8، لا يمكن لعلامة # أن تعني تعليقًا إلا إذا لم يتبعها مباشرة '['. وإلا، فإنها تعني سمة دالة، والتي تعمل حتى ']':

/** 
* تحتوي هذه الفئة على توثيق نموذجي. 
* 
* @author Unknown 
*/ 
#[ Attribute ] 
class  MyAttribute  { 
    const  VALUE  =  'value' ; 
    // هذا تعليق مضمن. يبدأ بـ '//'، كما هو الحال في C++. 
    private  $value ; 
    # هذا تعليق مضمن على غرار يونكس، يبدأ بـ '#'. 
    public  function  __construct ( $value  =  null )  { 
        $this -> value  =  $value ; 
    } 
    /* 
    هذا تعليق متعدد الأسطر.

    لا يمكن تضمين هذه التعليقات. 
    */

}

التعليقات في Windows PowerShell

# تعليق على سطر واحد 
Write-Host  "مرحبا بالعالم!"

<#تعليق متعدد 
   السطور 
   #>

اكتب المضيف  "وداعا أيها العالم!"

تستخدم التعليقات المضمنة في Python علامة التجزئة (#)، كما هو الحال في المثالين الموجودين في هذا الكود:

# يقوم هذا البرنامج بطباعة "Hello World" على شاشة 
الطباعة ( "Hello World!" )   # لاحظ بناء الجملة الجديد

لا توجد تعليقات كتلة، كما هو موضح في هذه المقالة، من الناحية الفنية في بايثون. ^{[52] يمكن استخدام} حرف سلسلة مجردة يتم تمثيلها بسلسلة مقتبسة ثلاثية، ^[53] ولكن لا يتم تجاهلها بواسطة المترجم بنفس الطريقة التي يتم بها تجاهل تعليق "#". ^[52] في الأمثلة أدناه، تعمل السلاسل المقتبسة الثلاثية بهذه الطريقة كتعليقات، ولكن يتم التعامل معها أيضًا كسلاسل توثيق :

""" 
بافتراض أن هذا هو الملف mymodule.py، فإن هذا السلسلة، كونها 
العبارة الأولى في الملف، ستصبح 
سلسلة توثيق وحدة "mymodule" عند استيراد الملف. 
"""

class  MyClass : 
"""سلسلة توثيق الفصل"""    

    def  my_method ( self ): 
"""سلسلة توثيق الطريقة"""        

def  my_function (): 
"""سلسلة توثيق الوظيفة"""    

تبدأ التعليقات المضمنة في Ruby برمز #.

لإنشاء تعليق متعدد الأسطر، يجب وضع "=begin" في بداية السطر، ثم يتم تجاهل كل شيء حتى "=end" الذي يبدأ السطر. يؤدي إضافة مسافة بعد علامة يساوي في هذه الحالة إلى حدوث خطأ في بناء الجملة.

يضع "هذا ليس تعليقًا" 

# هذا تعليق

يضع "هذا ليس تعليقًا" 

=بداية

كل ما يدخل في هذه السطور

هو فقط للقارئ البشري

=نهاية

يضع "هذا ليس تعليقًا" 

تكون التعليقات القياسية في SQL في شكل سطر واحد فقط، باستخدام شرطتين:

-- هذا تعليق من سطر واحد 
-- يتبعه سطر ثانٍ 
SELECT COUNT ( * ) FROM Authors WHERE Authors . name = 'Smith' ; -- ملاحظة: نريد فقط 'smith' -- يظهر هذا التعليق بعد كود SQL 
        
           
                                     

بدلاً من ذلك، يتم دعم صيغة تعليق مطابقة لنمط "التعليق الكتلي" المستخدم في صيغة C وJava بواسطة Transact-SQL و MySQL و SQLite و PostgreSQL و Oracle . ^{[54] [55] [56] [57] [58]}

يدعم MySQL أيضًا التعليقات من علامة التجزئة (#) إلى نهاية السطر.

تبدأ التعليقات المكونة من سطر واحد بعلامتي شرطة مائلتين للأمام (//):

//هذا تعليق.

تبدأ التعليقات متعددة الأسطر بعلامة مائلة للأمام تليها علامة النجمة (/*) وتنتهي بعلامة النجمة تليها علامة مائلة للأمام (*/):

/* هذا أيضًا تعليق 
ولكنه مكتوب على عدة أسطر. */

يمكن تضمين التعليقات متعددة الأسطر في Swift داخل تعليقات متعددة الأسطر أخرى. يمكنك كتابة التعليقات المتداخلة عن طريق بدء كتلة تعليق متعددة الأسطر ثم بدء تعليق متعدد الأسطر ثانٍ داخل الكتلة الأولى. ثم يتم إغلاق الكتلة الثانية، متبوعة بالكتلة الأولى:

/* هذه هي بداية التعليق متعدد الأسطر الأول. 
/* هذا هو التعليق متعدد الأسطر الثاني المتداخل. */ 
هذه هي نهاية التعليق متعدد الأسطر الأول. */

يتم تقديم التعليقات في XML (أو HTML) باستخدام

< !--

ويمكن أن تنتشر على عدة أسطر حتى النهاية،

-->

على سبيل المثال،

<!-- حدد السياق هنا --> 
<param name= "context" value= "public" />   

من أجل التوافق مع SGML ، لا يُسمح باستخدام السلسلة "--" (علامة الوصل المزدوجة) داخل التعليقات.

في اللغات المفسرة، تكون التعليقات مرئية للمستخدم النهائي للبرنامج. في بعض الحالات، مثل أقسام الكود التي يتم "التعليق عليها"، قد يمثل هذا ثغرة أمنية . ^[59]

• Docstring ، نوع محدد من التعليقات التي يتم تحليلها والاحتفاظ بها طوال وقت تشغيل البرنامج.
• Shebang ، استخدام #! كتوجيه للمترجم في البرامج النصية على أنظمة شبيهة بنظام يونكس
• علامة تعليق HTML
• البرمجة المتعلمة ، نموذج التوثيق البديل
• قواعد كتابة التعليقات في لغات البرمجة المختلفة
• التعليق (توجيه CONFIG.SYS)
• REM (توجيه CONFIG.SYS)

• Movshovitz-Attias, Dana وCohen, William W. (2013) نماذج اللغة الطبيعية للتنبؤ بالبرمجة التعليقات. في جمعية اللغويات الحاسوبية (ACL)، 2013.

• كيفية كتابة التعليقات بقلم دينيس كروكوفسكي
• توثيق الكود المصدري كدليل مستخدم مباشر بواسطة PTLogica
• كيفية كتابة التعليقات لأداة Javadoc

Original text

Rate this translation

Your feedback will be used to help improve Google Translate