النمط القياسي لكود دلفي

دليل أسلوب الكائن باسكال - بقلم تشارلز كالفيرت

(دليل أسلوب ترميز الكائنات بـ Pascal - ترجمة: تومي تونغ)

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

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

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

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

يتوفر منسق مجاني تم تطويره بواسطة Egbert van Nes على:

http://www.slm.wau.nl/wkao/delforeexp.html

برنامج تجاري آخر لدلفي هو CrackerJax:

http://www.kineticsoftware.com/html/products.html

-------------------------------------------------- ----

1.0 مقدمة

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

1.1 الخلفية

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

1.2 شكرا

تعتمد التنسيقات الموجودة في هذه المقالة على العمل المنجز لتحديد معايير النمط للغة Java. ليس لجافا أي تأثير على قواعد تنسيق الكود المصدري لـ Object Pascal، لكن التوثيق الموجود على موقع Sun الإلكتروني هو الأساس لهذه المقالة. في بعض الأماكن الخاصة، تم استلهام أسلوب وشكل هذه المقالة إلى حد كبير من "دليل أسلوب البرمجة لـ Java WorkShop وJava Studio Programming" (Achut Reddy، "Coding Guide for Java WorkShop وJava Studio"). يمكن العثور على المقالة على عنوان URL هذا: http://www.sun.com/workshop/java/wp-coding

لقد ساهم فريق دلفي بشكل كبير في إكمال هذه المقالة. في الواقع، لولا مساعدتهم، لم تكن هذه المقالة لتكتمل.

2.0 الملفات المصدرية

تنقسم كود مصدر Object Pascal بشكل أساسي إلى ملفات مصدر واحدة وملفات مشروع، وكلها تتبع نفس الاتفاقية. ملفات مشروع دلفي لها امتداد .DPR. وهو الملف الرئيسي للمشروع. أي ملف وحدة مستخدم في المشروع له ملحق .PAS. يمكن أن تلعب الملفات الأخرى، مثل الملفات الدفعية أو ملفات HTML أو ملفات DLL أيضًا دورًا في المشروع، ولكن هذه المقالة تغطي فقط ملفات المشروع وملفات الوحدة.

2.1 تسمية الملف المصدر

يدعم Object Pascal أسماء الملفات الطويلة. إذا كنت تستخدم عدة كلمات لتكوين اسم واحد، فمن الأفضل استخدام حرف كبير أولي لكل كلمة: MyFile.pas. ويعتبر هذا بين قوسين أو حالة الجمل. يجب أن تكون الامتدادات بأحرف صغيرة. لأسباب تاريخية، غالبًا ما يستخدم كود مصدر دلفي نمط التسمية 8:3، لكن ليس من الضروري أن يتقيد المطورون بالقواعد المذكورة أعلاه ويلجأون إلى استخدام فريق دلفي.

إذا كنت تترجم ملف رأس C/C++، فيجب أن يحتفظ ملف Pascal الذي تترجمه بنفس اسم الملف الرئيسي مثل ملف الرأس C/C++، ويستخدم .PAS كملحق. على سبيل المثال: Windows.h -> Windows.pas. إذا أجبرك بناء جملة Pascal على دمج عدة ملفات رأسية في ملف وحدة واحد، فسيتم استخدام اسم ملف الرأس الذي يحتوي على ملفات الرأس الأخرى كاسم لملف الوحدة الجديد. على سبيل المثال: يحتوي Windows.h على الملف WinBase.h، ثم يُسمى ملف الوحدة الجديد Windows.pas.

2.2 تنظيم الملف المصدر

يجب أن تحتوي جميع ملفات وحدة Object Pascal على العناصر التالية بالترتيب التالي:

حقوق الطبع والنشر/تعليقات حظر الهوية

اسم الوحدة

قطاع الواجهة

جزء التنفيذ

"نهاية" فاصلة.

ويجب أن يكون هناك سطر فارغ واحد على الأقل بين كل قسم.

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

 {*************************************************************************************************************************************************************************** * *****}
 { }
 { مكتبة بورلاند دلفي للمكونات المرئية }
 { }
 { حقوق الطبع والنشر (ج) لعام 1995،98 لشركة Inprise }
 { }
 {*************************************************************************************************************************************************************************** * *****}
 أزرار الوحدة ؛
 {$S-،W-،R-}
 {$C التحميل المسبق}
 واجهة
 الاستخدامات
 ويندوز، الرسائل، الطبقات،
 الضوابط والنماذج والرسومات،
 ستدكترلس، إكستكترلس، كومكترل؛

إذا وضعت قسم الكتابة قبل قسم const، أو قمت بخلط الاثنين، فلن يكون له أي تأثير.

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

 تطبيق
 الاستخدامات
 كونستس، سيسوتيلس، أكتنليست،
 ImgList;

{$R أزرار.RES}

2.2.1 تعليقات حقوق الطبع والنشر/حظر الهوية

يجب أن يبدأ كل ملف مصدر بتعليق محظور يحتوي على معلومات الإصدار وإشعار حقوق الطبع والنشر القياسي. يمكن أن تبدو معلومات الإصدار كما يلي:

 {*************************************************************************************************************************************************************************** * *****}
 { }
 {الحاجيات وافرة}
 { }
 { حقوق الطبع والنشر (ج) 1995،98 لشركتك }
 { }
 {*************************************************************************************************************************************************************************** * *****}

يجب أن يحتوي إشعار حقوق النشر على الأسطر التالية على الأقل:

حقوق الطبع والنشر (ج) مالك حقوق الطبع والنشر العام

إذا كنت طرفًا ثالثًا يقوم بتطوير برنامج لـ Borland، فيمكنك إضافة اسمك في نهاية حقوق الطبع والنشر:

 {*************************************************************************************************************************************************************************** * *****}
 { }
 { مكتبة بورلاند دلفي للمكونات المرئية }
 { حقوق الطبع والنشر (ج) 1995,99 لشركة Borland International }
 { تم الإنشاء بواسطة مشروع JEDI }
 { }
 {*************************************************************************************************************************************************************************** * *****}

2.2.2 إعلان الوحدة

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

وحدة MyUnit؛

ثم يجب أن يكون اسم ملف الوحدة MyUnit.pas. في نظام الملفات، يعمل بمثابة إدخال لهذا الملف.

2.2.3 بيان الاستخدامات

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

this.usesMyUnit;

يتم فصل اسم كل وحدة عن اسم الوحدة المجاورة لها بفاصلة، ويتبع اسم الوحدة الأخيرة بفاصلة منقوطة:

 الاستخدامات
 Windows، SysUtils، Classes، Graphics، Controls، Forms،
 TypInfo;
 ومن الصحيح أيضًا إضافة اسم الوحدة بدءًا من سطر الاستخدامات التالي وإضافة اسم الوحدة مباشرة بعد الاستخدامات.
 يستخدم Windows، SysUtils، Classes، Graphics، Controls، Forms،
 TypInfo;

يمكنك تنسيق قائمة أسماء الوحدات الخاصة بك لتشمل الحد الأقصى البالغ 80 حرفًا، أو أن يكون لها سطر واحد لكل اسم وحدة.

2.2.4 تعريفات الفئة والواجهة

تبدأ تعريفات الفئة بمسافتين، متبوعة بالبادئة "T". يجب أن تكون البادئة كبيرة، ويجب أن تبدأ كل كلمة مضمنة بحالة كبيرة. لا تستخدم حرف علامة التبويب "Tab" في التعليمات البرمجية المصدر لـ Object Pascal. مثال:

تميكلاس

اتبع المعرف بمسافة، ثم علامة يساوي، ثم فئة الكلمة، والتي يجب أن تكون صغيرة:

TMyClass = class

إذا ورثت صفك من أحد الأسلاف، فستحتاج إلى إضافة قوسين يمين ويسار يحتويان على فئة السلف:

TMyClass = فئة (TObject)

مؤشرات النطاق عبارة عن مسافتين من الهامش وتظهر بالترتيب التالي:

TMyClass = clss(TObject)

خاص

يحمي

عام

نشرت

نهاية؛

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

 TMyClass = الفئة (TObject)
 خاص
 FMyDate: عدد صحيح؛
 الدالة GetDate: عدد صحيح؛
 الإجراء SetData(Value: Integer);
 عام
 نشرت
 الخاصية MyData: قراءة عدد صحيح لـ GetData وكتابة SetData؛
 نهاية ؛

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

اصطلاح التسمية

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

MyIdentifier

MyFTPClass

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

WM_LBUTTONDOWN، لا تكتب wm_LButtonDown.

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

اسم جيد:

نموذج العنوان، ArrayIndexOutOfBoundsException

الأسماء السيئة:

ManageLayout // استخدم العبارة الفعلية

delphi_is_new_to_me // استخدم التسطير

3.1 تسمية الوحدة

انظر إعلان الوحدة

3.2 تسمية الفئة/الواجهة

راجع إعلان الفئة/الواجهة

3.3 تسمية المجال/الحقل

استخدم تنسيق CamelCase. ابدأ بحرف كبير "F" وأعلن أن جميع البيانات خاصة، باستخدام الخصائص أو الحروف والمحددات لتوفير الوصول العام. على سبيل المثال: استخدم اسم GetSomething لتسمية دالة تُرجع قيمة حقل/حقل داخلي، واستخدم SetSomething لتسمية إجراء يقوم بتعيين قيمة حقل/حقل.

لا تستخدم كافة الأحرف الكبيرة في الأقسام الثابتة إلا إذا كانت مطلوبة لترجمة ملف الرأس.

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

صحيح:

FMyString: سلسلة؛

غير صحيح:

lpstrMyString: سلسلة؛

بالطبع يتم الحفاظ على التسميات المجرية في تعريف نوع التعداد:

TBitBtnKind = (bkCustom، bkOK، bkCancel، bkHelp،

بكنعم، بكلا، بككلوز، بكابورت، بك ريتري،

bkignore، bkAll)؛

في هذه الحالة يتم إدراج الحرف bk قبل كل عنصر من نوع التعداد هذا. bk يعني ButtonKind.

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

تجنب استخدام المتغير "l" (L) لأنه من الصعب التمييز بينه وبين "1" (واحد) على الطابعة أو الشاشة.

3.4 تسمية الطريقة

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

// تسمية الطريقة الجيدة:

ShowStatus، DrawCircle، AddLayoutComponent

// تسمية الطريقة سيئة:

MouseButton // عبارة اسمية، لا توجد وظيفة وصف

drawCircle // ابدأ بحرف صغير

add_layout_component // يتم استخدام التسطير

// وظائف الطرق التالية ليست واضحة بما فيه الكفاية. هل يبدأ تشغيل الخدمة (الأفضل: StartServer) أو تحديد ما إذا كانت الخدمة قيد التشغيل (الأفضل: IsServerRunning)؟

ServerRunning // عبارة فعلية وليست أمرًا

يجب أن تسمى طريقة الحصول على بعض خصائص الفئة أو تعيينها GetProperty أو SetProperty على التوالي، حيث تمثل الخاصية اسم الخاصية. على سبيل المثال:

الحصول على الارتفاع، تعيين الارتفاع

يجب تسمية الطريقة التي تختبر خاصية منطقية لفئة ما باسم IsVisible، حيث يمثل Visible اسم الخاصية. على سبيل المثال:

يمكن تغيير حجمه، وهو مرئي

3.5 تسمية المتغيرات المحلية

قواعد تسمية المتغيرات المحلية هي نفس قواعد تسمية الحقول/الحقول، باستثناء عدم استخدام "F". انظر القسم 3.3.

3.6 الكلمات المحجوزة

يجب أن تكون الكلمات والمؤشرات المحجوزة بأحرف صغيرة. قد يكون هذا مربكًا بعض الشيء في بعض الأحيان. على سبيل المثال: عدد صحيح هو معرف ويظهر مع الحرف الأول الكبير. الكلمات المحجوزة للسلسلة كلها بأحرف صغيرة.

3.7 نوع الإعلان

تبدأ جميع إعلانات أسماء النوع بالحرف T وتتبع نفس اسم الفئة.

4.0 استخدام المساحة البيضاء

4.1 خطوط فارغة

يمكن للأسطر الفارغة تحسين إمكانية القراءة من خلال تجميع مقاطع التعليمات البرمجية المرتبطة منطقيًا. يمكن أيضًا استخدام سطر فارغ في الأماكن التالية:

بعد كتلة تعليق حقوق الطبع والنشر، إعلان الحزمة (الحزمة)، وقسم الاستيراد (استيراد).

بين إعلانات الطبقة.

بين إعلانات الطريقة.

4.2 المساحات

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

4.2.2 لا ينبغي استخدام المسافات:

بين اسم الطريقة وقوس الفتح؛

قبل أو بعد عامل التشغيل .(dot)؛

بين المشغل الأحادي ومعامله؛

بين النوع والتعبير الذي يلقيه؛

بعد القوس الأيسر وقبل القوس الأيمن؛

بعد القوس المربع الأيسر وقبل القوس المربع الأيمن؛

قبل الحظر؛

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

// الاستخدام الصحيح:

وظيفة TMyClass.MyFunc(var Value: Integer);

MyPointer := @MyRecord;

MyClass := TMyClass(MyPointer);

MyInteger := MyIntegerArray[5];

// الاستخدام غير الصحيح:

الدالة TMyClass.MyFunc( var Value: Integer );

MyPointer := @MyRecord;

MyClass := TMyClass ( MyPointer ) ;

MyInteger := MyIntegerArray [ 5 ] ;

4.3 المسافة البادئة

يجب عليك دائمًا وضع مسافة بادئة لجميع مستويات المسافة البادئة بمسافتين. بمعنى آخر، يتم وضع مسافة بادئة للمستوى الأول بمسافتين، والمستوى الثاني بمسافة بادئة بأربع مسافات، والمستوى الثالث بمسافة بادئة بستة مسافات... لا تستخدم علامة التبويب حرف Tab.

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

4.4 الاستمرار

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

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

//صحيح:

 وظيفة CreateWindowEx(dwExStyle: DWord;
 lpClassName: PChar;
 dwStyle: DWORD؛ X، Y، nWidth، nHeight: عدد صحيح؛
 hWndParent: HWND؛ hMenu: HMENU؛
 lpParam: المؤشر ): HWND;
 إذا ((X = Y) أو (Y = X) أو
 (Z = P) أو (F = J) إذن
 يبدأ
 س := ي؛
 نهاية ؛

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

//صحيح:

الإجراء Foo(Param1: عدد صحيح؛ Param2: عدد صحيح)؛

//خطأ:

الإجراء Foo( Param :Integer; Param2:Integer);

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

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

//خطأ:

 بينما يبدأ (LongExpression1 أو LongExpression2) .
 //افعل شيئًا ما
 //DoSomethingElse;
 نهاية ؛

//صحيح

 بينما يقوم (LongExpression1 أو longExpression2).
 يبدأ
 //افعل شيئًا
 //DoSomethingElse;
 نهاية ؛
 إذا (LongExpressiong1) أو
 (LongExpression2) أو
 (LongExpression3) ثم

5.0 تعليقات

تدعم لغة Object Pascal نوعين من التعليقات: التعليقات المجمعة والتعليقات ذات السطر الواحد. فيما يلي بعض إرشادات استخدام التعليقات التوضيحية:

· من المفيد وضع تعليقات في أعلى الوحدة توضح غرض الوحدة

· من المفيد وضع التعليقات قبل تصريحات الفصل

· من المفيد تعيين التعليقات التوضيحية قبل إعلانات الطريقة

· تجنب التعليقات ذات المعاني الواضحة

i := i + 1; //أضف واحدًا إلى i

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

· تجنب وضع معلومات في التعليقات التي تبدو غير صالحة

· تجنب تضمين العلامات النجمية أو الرموز المطبعية الأخرى في حدود التعليقات

· يجب وضع علامة "؟؟؟:" على تعليقات ساعة الصفر، أي التعليقات التي تحتاج إلى تغيير أو حذف، قبلها، بحيث يسهل العثور عليها. من الناحية النظرية، يجب حذف جميع التعليقات ذات الوقت الصفري قبل إصدار البرنامج.

// ؟؟؟: قم بتغيير هذا لاستدعاء الفرز عندما يتم إصلاحه

List.MySort;

5.1 حظر التعليقات

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

{ محرر العقارات

تحرير خاصية مكون، أو قائمة المكونات،

تم تحديده في Object Inspector

يتم إنشاء المحرر بناءً على نوع الملف

الخاصية التي يتم تحريرها على النحو الذي تحدده الأنواع

مسجل بواسطة...

إلخ...

GetXxxValue

يحصل على قيمة العقار الأول في

خاصية الخصائص

طريقة TProperty GetXxxValue لاسترداد ملف

قيمة.

SetXxxValue يعين قيمة كافة الخصائص

في خاصية الخصائص

طرق TProperty SetXxxxValue لتعيين القيمة }

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

يجب أن يسبق التعليق الشامل الذي يشرح الغرض من الطريقة إعلان الطريقة.

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

// صحيح

{ TMyObject.MyMethod

يتيح لك هذا الروتين تنفيذ التعليمات البرمجية }

الإجراء TMyObject.MyMethod؛

يبدأ

نهاية؛

// غير صحيح

الإجراء TMyObject.MyMethod؛

{*************************************************************************************************************************************************************************** * ****

TMyObject.MyMethod

يتيح لك هذا الروتين تنفيذ التعليمات البرمجية.

*************************************************************************************************************************************************************************** * *****}

يبدأ

نهاية؛

النوع الثاني من التعليق الكتلي يحتوي على حرفين، قوسين وعلامة النجمة: (* *). يُسمى هذا أحيانًا بتعليق قوس النجمة. تكون هذه التعليقات التوضيحية مفيدة بشكل عام فقط أثناء تطوير التعليمات البرمجية، وتتمثل فائدتها الرئيسية في أنها تسمح للتعليقات التوضيحية المتداخلة بأن تكون أقل من مستويين. لا يدعم Object Pascal نفس النوع من تداخل التعليقات، لذلك يوجد مستوى واحد فقط من التداخل: الأقواس المتعرجة داخل الأقواس النجمية، أو الأقواس النجمية داخل الأقواس المتعرجة. سيتم تجاهل تعليقات Standard Pascal للأنواع الأخرى ضمن التعليقات التوضيحية من هذا النوع طالما لم تقم بدمجها. لذلك، يمكنك استخدام بناء الجملة هذا للتعليق على كتلة كبيرة من التعليمات البرمجية التي تحتوي على كل من التعليمات البرمجية والتعليقات:

(* الإجراء TForm1.Button1Click(Sender: TObject);

 يبدأ
 افعل هذا؛ // ابدأ العملية
 افعل ذلك // متابعة التكرار
 { نحتاج إلى طريقة للإبلاغ عن الأخطاء هنا، ربما باستخدام
 محاولة منع أخيرا ؟؟؟ }
 CallMoreCode; // إنهاء العملية
 نهاية ؛ *)

في هذه الحالة، يتم التعليق على طريقة Button1Click بأكملها، بما في ذلك أي تعليقات فرعية بداخلها.

5.2 التعليقات ذات السطر الواحد

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

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

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

// افتح قاعدة البيانات

الجدول 1. مفتوح؛

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

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

 إذا ( ليس مرئيًا) إذن
 خروج؛ // لا شيء للقيام به
 Inc(StrLength); // حجز مساحة للفاصل الفارغ

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

عطوف

6.1 تنظيم الفصول الدراسية

يجب أن يتبع تنظيم الهيئات الصفية الترتيب التالي:

· إعلان المجال/الحقل

· إعلان الطريقة

· تعريف السمة

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

6.1.1 مستويات الوصول

باستثناء التعليمات البرمجية التي تم إنشاؤها بواسطة IDE، يجب أن تكون محددات النطاق للفئات بالترتيب التالي:

· بيان خاص

· بيان الحماية

· بيان عام

· البيان المنشور

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

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

6.1.8 إعلان المنشئ

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

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

6.2 إعلان الطريقة

إذا أمكن، يجب أن تظهر إعلانات الطريقة في سطر واحد.

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

أمثلة:

 الإجراء ImageUpdate(Image img, infoflags: Integer,
 x: عدد صحيح، y: عدد صحيح، w: عدد صحيح، h: عدد صحيح)

7.0 واجهة

إعلان الواجهة له نفس شكل إعلان الفئة:

 اسم الواجهة = الواجهة ([ الواجهة الموروثة ])
 InterfaceBody
 نهاية ؛

يجب وضع مسافة بادئة لإعلانات الواجهة بمسافتين، وأجسام الواجهة بأربع مسافات، وأحرف النهاية بمسافتين.

لا توجد حقول/حقول في إعلان الواجهة. لكن السمات يمكن أن تظهر.

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

ما لم يُذكر خلاف ذلك، فإن إعلانات الواجهة لها نفس نمط الإعلانات من نفس النوع.

7.1 تنظيم واجهة الجسم

يمكن تنظيم جسم الواجهة بالترتيب التالي:

· إعلان طريقة الواجهة

· إعلان سمة الواجهة

يتم الإعلان عن أساليب وخصائص الواجهة بنفس نمط الفئات.

8.0 بيان

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

// هذه عبارة واحدة:

أ := ب؛

// هذه عبارة مركبة:

 يبدأ
 ب := ج؛
 أ := ب؛
 نهاية ؛

8.0.1 إعلان واحد

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

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

 قيمة بلدي :=
 MyValue + (SomeVeryLongStatement / OtherLongStatement);

8.1.1 إعلانات التخصيص والتعبير

يمكن أن يكون هناك عبارة واحدة على الأكثر في كل سطر.

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

 أ := ب + ج Inc(Count) ;
 أ := ب + ج ;
 Inc( العدد );

8.1.2 إعلان المتغير المحلي

تستخدم المتغيرات المحلية أيضًا تنسيق CamelCase. لا تستخدم الحرف "F" المخصص للحقول/الحقول في إعلانات الفئة.

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

 فار
 بياناتي: عدد صحيح؛
 MyString: سلسلة ؛

يمكنك الإعلان عن متغيرات متعددة من نفس النوع في نفس السطر:

 فار
 ArraySize، ArrayCount: عدد صحيح؛

لا يُنصح باستخدام عادة الإعلان هذه في إعلانات الفصل.

8.1.3 إعلان الصفيف

من الشائع دائمًا وضع مسافة قبل قوس الفتح وبعد قوس الإغلاق:

 يكتب
 TMyArray = الصفيف [0..100] من Char؛

8.2.3 إذا كان البيان

يجب أن تظهر عبارة if في سطرين على الأقل:

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

//خطأ:

 إذا كان A = B، فافعل شيئًا ما؛

//صحيح

 إذا أ = ب ثم
 افعل شيئًا;

إذا كانت عبارة if مركبة، فيجب أن يكون هناك سطر جديد لكل محدد:

//خطأ:

 إذا أ = ب ثم ابدأ
 افعل شيئًا;
 DoSomethingElse;
 نهاية أخرى تبدأ
 افعل هذا؛
 افعل ذلك؛
 نهاية ؛

//صحيح

 إذا أ = ب ثم
 يبدأ
 افعل شيئًا;
 DoSomethingElse;
 نهاية
 آخر
 يبدأ
 افعل هذا؛
 افعل ذلك؛
 نهاية ؛

يمكن اعتماد بعض الاختلافات التالية:

//صحيح

 إذا كان الشرط ثم
 يبدأ
 افعل هذا؛
 نهاية آخر
 يبدأ
 افعل ذلك؛
 نهاية ؛

//صحيح

 إذا كان الشرط ثم
 يبدأ
 افعل هذا؛
 نهاية
 آخر
 افعل شيئًا;

//صحيح

 إذا كان الشرط ثم
 يبدأ
 افعل هذا؛
 نهاية آخر
 DoSoemthing;

// قد لا يتم الاهتمام بالطريقة التالية، لكنها تستحق الثناء:

 إذا كان الشرط ثم
 افعل هذا
 آخر افعل ذلك؛

8.2.4 للبيان

مثال:

// غير صحيح

 لأني := 0 إلى 10 تبدأ
 افعل شيئًا;
 DoSomethingElse;
 نهاية ؛

// صحيح

 لأني := 0 إلى 10 افعل
 يبدأ
 افعل شيئًا;
 DoSomethingElse;
 نهاية ؛

8.2.5 أثناء البيان

مثال:

// غير صحيح

 بينما يبدأ x &lt ;
 افعل شيئًا;
 DoSomethingElse;
 نهاية ؛

// صحيح

 بينما x &lt ;
 يبدأ
 افعل شيئًا;
 DoSomethingElse;
 نهاية ؛

8.2.6 كرر حتى البيان

مثال:

// صحيح

 يكرر
 س := ي;
 ي := UpdateValue;
 حتى ي = 25؛

8.2.7 بيان الحالة

مثال:

// صحيح

 مراقبة الحالة.محاذاة
 alLeft, alNone: NewRange := Max(NewRange, Position);
 alRight: Inc(AlignMargin, Control.Width);
 نهاية ؛

// صحيح

 حالة x من
 سي ستارت:
 يبدأ
 ي := UpdateValue;
 نهاية ؛
 csBegin: x := j;
 كستيميوت:
 يبدأ
 ي := س؛
 x := UpdateValue;
 نهاية ؛
 نهاية ؛

// صحيح

 رمز تمرير الحالة
 SB_LINEUP، SB_LINEDOWN:
 يبدأ
 Incr := FIncrement div FLineDiv;
 FinalIncr := FIncrement mod FLineDiv;
 Count := FLineDiv;
 نهاية ؛
 SB_PAGEUP، SB_PAGEDOWN:
 يبدأ
 incr := FPageIncrement;
 FinalIncr := Incr mod FPageDiv;
 Incr := Incr div FPageDiv;
 Count := FPageDiv;
 نهاية ؛
 آخر
 العدد := 0;
 إنكر := 0;
 FinalIncr := 0;
 نهاية ؛

8.2.8 بيان المحاولة

//صحيح

 يحاول
 يحاول
 EnumThreadWindows(CurrentThreadID, @Disable, 0);
 النتيجة := TaskWindowList;
 يستثني
 EnableTaskWindows(TaskWindowList);
 يرفع ؛
 نهاية ؛
 أخيراً
 TaskWindowList := SaveWindowList;
 TaskActiveWindow := SaveActiveWindow;
 نهاية ؛
 مدونة المؤلف: http://blog.csdn.net/sailerbai/