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

يمكن للتعليقات أن توضح نية المؤلف - أي سبب وجود الكود على هذا النحو. يرى البعض أن وصف وظيفة الكود أمرٌ زائد عن الحاجة. فالحاجة إلى شرح الوظيفة دليل على أنها معقدة للغاية وتحتاج إلى إعادة صياغة.

"لا توثق الكود السيئ - أعد كتابته." ^{[ 9 ]}

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

قد توضح التعليقات سبب اختيار كتابة كود يخالف الأعراف أو أفضل الممارسات. على سبيل المثال:

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

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

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

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

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

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

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

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

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

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

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

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

تدعم بعض محررات شفرة المصدر إمكانية التهيئة عبر البيانات الوصفية في التعليقات. ^{[ 15 ]} ومن الأمثلة على ذلك ميزة "modeline" في محرر Vim ، والتي تُهيئ معالجة أحرف الجدولة. على سبيل المثال:

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

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

على الرغم من أن البعض يدّعي أن توثيق واجهات برمجة التطبيقات (API) يمكن أن يكون بجودة أعلى عند كتابته بطريقة تقليدية ويدوية، إلا أن البعض الآخر يرى أن تخزين معلومات التوثيق في تعليقات الكود يُبسّط عملية التوثيق، ويزيد من احتمالية تحديث التوثيق باستمرار. ^{[ 16 ]} ومن الأمثلة على ذلك Javadoc وDdoc و Doxygen و Visual Expert و PHPDoc . وتدعم لغات Python و Lisp و Elixir و Clojure أشكالًا مختلفة من سلاسل التوثيق . ^{[ 17 ]} وتُطبّق لغات C# و F# و Visual Basic .NET ميزة مشابهة تُسمى "تعليقات XML"، والتي يقرأها IntelliSense من تجميعة .NET المُجمّعة . ^{[ 18 ]}

يمكن تضمين تمثيل فني باستخدام رموز ASCII مثل الشعار أو الرسم التخطيطي أو مخطط التدفق في التعليق. ^{[ 19 ]}

يوضح جزء الكود التالي مسار عملية نص برمجي لإدارة النظام ( ملف نص برمجي لنظام ويندوز ). على الرغم من أن قسمًا يُشير إلى الكود يظهر كتعليق، إلا أن الرسم التخطيطي موجود في قسم بيانات XML (CDATA) ، وهو ليس تعليقًا بالمعنى التقني، ولكنه يؤدي الغرض نفسه هنا. ^{[ 20 ]} مع أن هذا الرسم التخطيطي كان من الممكن أن يكون ضمن تعليق، إلا أن هذا المثال يوضح حالةً اختار فيها المبرمج عدم استخدام تعليق كوسيلة لتضمين الموارد في الكود المصدري. ^{[ 20 ]}

<!-- بداية: 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>

أحيانًا، تصف التعليقات عمليات التطوير المتعلقة بالبرنامج. على سبيل المثال، قد تصف التعليقات كيفية بناء البرنامج أو كيفية إرسال التغييرات إلى مسؤول صيانة البرنامج .

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

ومن الأمثلة الأخرى توجيهات المترجم الفوري :

• يُستخدم " shebang " في نظام Unix #!في السطر الأول من البرنامج النصي للإشارة إلى المفسر المراد استخدامه.
• "التعليقات السحرية" التي تحدد ترميز ملف المصدر، ^{[ 22 ]} على سبيل المثال PEP 263 الخاص بلغة بايثون. ^{[ 23 ]}

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

#!/usr/bin/env python3 # -*- coding: UTF-8 -*- print ( "Testing" )

يبحث مُصرّف gcc (منذ عام 2017) عن تعليق في عبارة switch إذا كان أحد الحالات ينتقل إلى الحالة التالية. إذا لم يُعثر على إشارة صريحة إلى هذا الانتقال، يُصدر المُصرّف تحذيرًا بشأن مشكلة برمجية محتملة. يُعدّ إدراج مثل هذا التعليق حول الانتقال إلى الحالة التالية عرفًا راسخًا، وقد قام المُصرّف بتقنين هذه الممارسة. ^{[ 24 ]} على سبيل المثال:

التبديل ( الأمر ) {case CMD_SHOW_HELP_AND_EXIT :do_show_help ();/* السقوط من خلال */حالة CMD_EXIT :do_exit ();استراحة ؛}

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

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

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

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

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

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

String s = "Wikipedia" ; /* يُسند القيمة "Wikipedia" إلى المتغير s. */

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

تستخدم العديد من لغات البرمجة التي تعتمد على الأقواس المعقوفة ، مثل C وC++ ومشتقاتها، الأقواس المعقوفة لتمييز التعليقات السطرية، //والتعليقات الكتلية /*. */في الأصل، كانت لغة C تفتقر إلى التعليقات السطرية، ولكن تمت إضافتها في C99 . ومن أبرز هذه اللغات: C وC++ و C# و D و Java و JavaScript و Swift . على سبيل المثال:

/* * التحقق مما إذا كان الحد الأقصى للعمليات يتجاوز الحد الأقصى المسموح به، مع التأكد من استبعاد المستخدم الجذر. * هذا ضروري لتمكين تسجيل الدخول من تعيين حد العمليات لكل مستخدم إلى قيمة أقل من العمليات التي يُشغلها المستخدم الجذر. */ bool isOverMaximumProcessLimit () { // TODO implement }

تسمح بعض اللغات، بما في ذلك D ^{[ 41 ]} و Swift ^{[ 42 ]} ، بتداخل التعليقات الكتلية بينما لا تسمح لغات أخرى بذلك، بما في ذلك C و C++.

مثال على الكتل المتداخلة في لغة D:

// تعليق سطري /*  تعليق كتلة */ /+ بداية الكتلة الخارجية  /+ الكتلة الداخلية +/  نهاية الكتلة الخارجية +/

مثال على الكتل المتداخلة في لغة Swift:

/* هذه بداية التعليق الخارجي.  /* هذا هو التعليق المتداخل. */ هذه نهاية التعليق الخارجي. */

من الأنماط الشائعة في العديد من لغات البرمجة النصية استخدام الفاصلة ( , ) لفصل التعليقات السطرية #. أما دعم التعليقات الكتلية فيختلف من لغة لأخرى. ومن أبرز هذه اللغات: Bash و Raku و Ruby و Perl و PowerShell و Python و R.

مثال في لغة R:

# هذا تعليق print ( "هذا ليس تعليقًا" ) هذا تعليق آخر

يضع "ليس تعليقًا" # هذا تعليق يضع "ليس تعليقًا" = بداية كل ما يُكتب في هذه الأسطر هو للقارئ البشري فقط = نهاية يضع "ليس تعليقًا"

=item Pod::List->new() إنشاء كائن قائمة جديد. يمكن تحديد الخصائص من خلال مرجع تجزئة كما يلي:  my $list = Pod::List->new({ -start => $., -indent => 4 }); =cut sub new { ... }

#`{{ "commenting out" this version toggle-case(Str:D $s) يُبدّل حالة كل حرف في سلسلة نصية:  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!"); }} sub toggle-case ( Str:D $s ) #`( this version of parens is used now ) { ... } 

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

""" في أعلى الملف، هذا هو توثيق الوحدة النمطية """class MyClass : """Class docstring"""def my_method ( self ): """Method docstring"""

تختلف لغات الترميز عمومًا في صيغة التعليقات، لكن بعض تنسيقات الترميز البارزة على الإنترنت، مثل HTML و XML، تُحدد التعليقات الكتلية بعلامة <b> <!--ولا تدعم التعليقات السطرية. مثال بلغة XML:-->

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

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

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

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

في أسلوب بيرد، يجب ترك مسافة فارغة قبل الرمز. > fact :: Integer -> Integer > fact 0 = 1 > fact ( n + 1 ) = ( n + 1 ) * fact n ويجب عليك ترك سطر فارغ بعد الكود أيضاً. 

\usepackage { verbatim } \newenvironment { code }{ \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 {}

--[[ تعليق طويل متعدد الأسطر ]]

مجموعة لغات برمجة متنوعة نسبيًا تُستخدم --لكتابة التعليقات في سطر واحد. من أبرز هذه اللغات: Ada و Eiffel و Haskell و Lua و SQL و VHDL . يختلف دعم التعليقات في الأسطر. مثال بلغة 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 ;