Godot: التعليقات التوضيحية في GDScript

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

<strong i="6">@description</strong> "Adds two numbers and returns the result."
<strong i="7">@parameter</strong> name=num1 type=float description="The first number"
<strong i="8">@parameter</strong> name=num2 type=float description="The second number"
<strong i="9">@returns</strong> type=float description="num1 and num2 added together"
func add(num1, num2):
    return num1 + num2

ويمكنني استدعاء دالة ، مثل get_annotations("add") ، والتي ستعيد هذه التعليقات التوضيحية؟ حتى لو لم يتعرف Godot على هذه التعليقات التوضيحية باعتبارها بعض الكلمات الرئيسية / التعليقات التوضيحية المضمنة؟

@ LikeLakers2 نعم ، هذا هو جوهر ذلك.

يعجبني ، لا أعرف التنفيذ وراءه ولكن في رمز GDscript سيبدو أنظف كثيرًا مما يبدو عليه الآن. خاصة بالنسبة لمثال setget.

هذا مفيد للغاية ، لكن يجب أن يسمح بعبارات سطر واحد لسهولة القراءة. على سبيل المثال،
يجب السماح بـ <strong i="6">@onready</strong> var a = $A . خلاف ذلك ، يضيف هذا عددًا كبيرًا من الأسطر الجديدة وسيضيع في هذه الحالة فائدة الاستعداد.

شيء مثل

<strong i="10">@onready</strong>
    var a = $A
    var b = $B
    var c = $C

قد يكون من المفيد تطبيق نفس التعليق التوضيحي على عدة عبارات.

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

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

لا أعتقد أن vnen ينوي إزالة الكلمات الرئيسية المختصرة القديمة رغم ذلك؟

يمكن أن يساعد وجود مقبض تمييز أيضًا.

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

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

#### وارد رأي غير شعبي:

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

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

أيضًا ، وجود 3 أسطر لكلمة رئيسية للتصدير أمر مرهق للغاية ، مقارنةً بتحديد كل شيء في سطر واحد فقط. على سبيل المثال: onready var my_sprite = $Sprite أكثر نظافة (بالنسبة لي على أي حال)

وفيما يتعلق بالنقطة رقم 4 ، يمكن عمل ذلك في محرر AFAIK. أيضًا ، imo ، وجود تعليقات توضيحية في كل مكان في الكود "لتعطيل تحذيرات معينة" قد يؤدي إلى رمز فوضوي للغاية

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

تتوافق معظم (إن لم يكن كل) تغييرات بنية GDScript مع التعليمات البرمجية القديمة. الهدف الرئيسي هو زيادة إنتاجية المطورين الذين يستخدمون GDScript ، على سبيل المثال:

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

أشعر فقط أنه قد يكون هناك انفصال محتمل بين مطوري اللعبة الفعليين والمساهمين.

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

[...] أخشى أن تبتعد gds أكثر فأكثر عن بساطتها ، هذا كل شيء. إنه بالفعل أكثر من كافٍ ...

إذا كانت جيدة بما يكفي بالفعل ، فلن نتلقى طلبات الميزات لها.

أيضًا ، وجود 3 أسطر لكلمة رئيسية للتصدير أمر مرهق للغاية ، مقارنةً بتحديد كل شيء في سطر واحد فقط. على سبيل المثال: var my_sprite = $ Sprite هو أكثر نظافة بكثير

لم يتم الانتهاء من بناء الجملة بعد. من المحتمل جدًا ألا تحل محل الكلمات الرئيسية onready و export الفور.

تعجبني الفكرة حقًا ، تمامًا مثل السمات في C #.

قد تكون التعليقات التوضيحية للفئات والإشارات ممتعة أيضًا.

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

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

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

أعتقد أن بناء الجملة التالي قد يكون مناسبًا للنظر في:

<strong i="7">@export</strong> type=String, hint=MULTILINE

أعتقد أن إضافة الفاصلة بين "المعلمات" سيجعلها أكثر اتساقًا مع البنية الحالية مثل:

export (String, MULTILINE) var my_var

الإصدار الأول أكثر تفصيلاً بقليل ، لكنني أعتقد أنه يجعله أيضًا أكثر وضوحًا ومع الإكمال التلقائي لن يؤذي كثيرًا :)

ينبغي إجراء المزيد من المناقشات النحوية من الآن فصاعدًا. بشكل عام أحب الفكرة.

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

من تعليق @ bojidar-bg ...

على أي حال ، سيمضي وقت طويل قبل أن تصبح التعليقات التوضيحية حقيقة واقعة.

هل يمكن لشخص ما أن يشرح مشكلة "الحجب" التي قد تؤخر هذا التنفيذ؟ هل هو مجرد معرفة بـ GDScript / القوى العاملة ، أم أن هناك ميزات محددة يجب تنفيذها مسبقًا لدعم التعليقات التوضيحية؟

حسنًا ، لقد مر وقت طويل منذ تعليقي ، لذا أعتقد أن هذا يثبت ذلك بالفعل؟

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

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

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

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

يمكن استخدامه أيضًا لحل هذه المشكلة التي عمرها 3 سنوات # 6204 بطريقة أنيقة:

<strong i="8">@export</strong>
<strong i="9">@export_tooltip</strong> "The name used when displaying this item in the inventory and in shops."
var display_name := ""

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

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

@connect("timeout")
func _on_Timer_timeout():
   ...

rluders بافتراض أن البرنامج النصي موجود على عقدة Timer ، ربما.

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

@connect("timeout", $Timer)
func _on_Timer_timeout():
  ...

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

سيكون من الأفضل أن نتمكن من إنشاء التعليقات التوضيحية الخاصة بنا + معالجات التعليقات التوضيحية الكاملة.

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

@connect("timeout", $Timer)
func _on_Timer_timeout():
  ...

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

كل ما يمكنني قوله هو أنني سعيد لأنني تعلمت gdscript قبل تنفيذ هذه الأشياء بسبب

@export_hint(ENUM)
@export_hint_string("Attack,Defense")
export var my_enum : int = 0

سيكون أمرًا شاقًا للغاية ويصعب تحليله بالنسبة لي ، كمبتدئ

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

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

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

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

إذا تم استخدام @ للبيانات الوصفية حصريًا ، ففي أي وقت يرى مطور جديد @ يتعرف عليه على أنه بيانات وصفية لا تؤثر على منطق الكود الخاص به. إذا كان سيؤثر على المنطق ، فمن المهم ألا نضيف مصطلحات جديدة تُستخدم أحيانًا كـ x وأحيانًا تستخدم كـ y .

الآن ، لتعديل متغير ، هناك بادئات ولاحقات وبدائل. هناك بعض الأشياء التي سأدرجها والتي ليست بالضرورة "معدّلات متغيرة" ، ولكن قد يراها المطورون الجدد بهذه الطريقة

• البادئات: onready ، export(...)
  
  
  
  • لكل منها نوع مختلف من السلوك. يؤثر onready على التحميل المتغير لوقت التشغيل ، أما export فهو نوع من تلميح / بيانات وصفية للمحرر. إن استخدامهم في نفس المكان يبدو وكأن سلوكهم يجب أن يكون مرتبطًا بطريقة ما ، في حين أنه ليس كذلك حقًا
  
  
• البدائل: class_name ، extends ، signal ، enum ، const ، func
  
  
  
  • تبدو هذه التنسيقات البديلة جيدة ، لكن التمييز بين "enum" و "const" من say أو ints أو String يبدو خيارًا غريبًا
  
  
• اللاحقات: setget
  
  
  
  • إن Setget في فئتها الخاصة على ما يرام ، لكنها تشبه export حيث أنها كلمة رئيسية للسكر للمطورين وليست تحولًا منطقيًا. أستطيع أن أرى الناس لديهم آراء مختلفة هنا ، رغم ذلك
  
  
• في مكان ما بينهما: كتابة var x : int = 5
  
  
  
  • تبدو عملية الكتابة في الفترات الفاصلة أمرًا غريبًا ، لا سيما عندما تكون "enum" و "const" كلمات رئيسية بديلة لـ var لتمثيل الشيء نفسه. بالتأكيد حجة مفادها أن const مشابه لـ setget من حيث أنه يعدل تجربة المطور أكثر من أداة لمنطق اللعبة نفسه.
  
  

فلنلقِ نظرة الآن على إضافة التعليقات التوضيحية.

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

• (المستوى 1) يمكنهم إنشاء لعبة تعرف فقط func و var وبعض مفاهيم البرمجة الأساسية مثل استدعاءات الوظائف والشرطية والحلقات
• (المستوى 2) ثم ينتقلون لتعلم السكر / الوظائف المفيدة ، مثل الإشارات ، والتعداد ، والتعداد
• (المستوى 3) يتعلمون الاختصارات ، مثل setget ، على استعداد
• (المستوى 3.1) يتعلمون السكر المخصص للمطور فقط ، والذي لن يغير لعبتهم ، ولكنه يغير عمليتهم ، بأشياء مثل الصادرات ، وأوصاف المحرر ، والأدوات ، والكتابة
• (المستوى 4) التوثيق البحت وهيكل المشروع

أشعر أن المستوى 3-4 هو الأهداف الرئيسية للتعليقات التوضيحية. هناك نوعان من عروض المصاعد التي سأقدمها لطلابي من أجل التطبيقين المختلفين:

• البيانات الوصفية البحتة: "للمساعدة في التوثيق والتعاون ، تعرف على التعليقات التوضيحية لإضافة بعض البيانات الوصفية إلى نصوصك البرمجية. فهي أقوى من مجرد استخدام التعليقات."
• اختصارات Dev / sugar: "إذا كنت تبحث عن تقليل الكود الخاص بك أو جعله أكثر قابلية للقراءة ، فقم بإلقاء نظرة على التعليقات التوضيحية. فهي تتيح لك وصف المتغيرات والوظائف مع توفير بعض أدوات التحرير والاختصارات."

لقد قمت بتدريس عدد من مطوري Godot ، وأعتقد أن عمل التعليقات التوضيحية على الأقل خيار من المستوى 3 ، وفي المستوى 4. أفضل ألا أضطر إلى إظهار رمز @ حتى يصبحوا بالفعل بناء بأكملها، ألعاب معقدة إلى حد معقول، ويتطلعون إلى تحسين عملية بهم.

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

نقاط محددة من الخيط:

• يجب أن يكونوا على ما يرام بالنسبة للتصدير ، لأن الصادرات ليست مهمة لأي لعبة
• يعد Onready اختصارًا مفيدًا في وقت مبكر ، ولكنه ليس ضروريًا حيث يمكن للمطورين الجدد البدء من خلال البدء في _ready واحتمال كتابة التعليقات التوضيحية المتداخلة يعني كتابة onready way مرات أقل
• setget هي بناء جملة غريب بالفعل ، وهي بالفعل لغتها الخاصة باعتبارها اللاحقة الوحيدة ، بحيث يمكن أن تكون موجودة تمامًا هناك
• الاتصال: كما أقود ، فهو مثالي بالفعل مع مصطلح استدعاء الوظيفة. قد يؤدي وجود طرق متعددة للاتصال إلى خلط مساحة البرنامج التعليمي / عينة التعليمات البرمجية. ربما يكون السماح للأشخاص بكتابة التعليقات التوضيحية الخاصة بهم أفضل من توحيد هذا الأمر ، بحيث يمكن للمطورين الذين يعملون في المشاريع المغلقة إنشاء مكتبة من التعليقات التوضيحية التي لن تخلط بالضرورة في الفضاء العام
• الأنواع: توجد الأنواع في مكان غريب في الوقت الحالي ، حيث تكون بعض مُعدِّلات الأنواع بدائل وبعض مُعدِّلات الأنواع في المنتصف. ربما تعمل التعليقات التوضيحية: @type(const int) @type(enum) ، مما يوحدهم جميعًا كسكر موجه للمطورين

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

انا لا يعجبني ذلك.
لا أرغب في الحصول على مجموعة من التعليقات التوضيحية لكل حقل وخاصية وطريقة

أنا أفضل الحصول على المزيد من الكلمات الرئيسية

إذا كان الأشخاص لا يحبون الكثير من الكلمات الرئيسية ، فيمكننا إزالة بعضها

export MyClass : Node2D # export replaces class_name, : replaces extends 

signal mySignal #signal is kept

group(MyHeader, "res://icon.png" )
export var my_property : Array(int) setget _set_my_property, _get_my_property # : replaces export type

var test = 0 # no need for onready. variables declared outside of _ready automatically try to be onready vars

#others are kept

أنا أتفق مع الاقتراح الأصلي تمامًا.

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

@ Shadowblitz16 كثير من هذه الاقتراحات محيرة للناس هنا ، للأسباب التالية ...

export MyClass : Node2D # export replaces class_name, : replaces extends

export ، class_name ، : ، و extends لكل منها تكوين 4 نقاط بيانات وأنظمة منفصلة تمامًا. لا يمكنك تبديلها ببساطة دون التأثير على أشياء أخرى بشكل غير قابل للاسترداد.

• export بتكوين كائن PropertyInfo الذي تم إرساله إلى المفتش لإنشاء محرر GUI.
• class_name بتسجيل البرنامج النصي كفئة عامة في ScriptServer. من الناحية الفنية لا علاقة له بنظام الكتابة. إنه جزء من "الكتابة الثابتة" الخاصة بـ GDScript فقط بقدر ما يحدث فقط لإنشاء مثيل عالمي للبرنامج النصي في وقت التحليل بدلاً من وقت التشغيل.
• يُستخدم : لتلميحات النوع الاختيارية . ما لم تقنع الناس بجعل GDScript مكتوبًا بشكل ثابت في جميع الأوقات و / أو تقترح صيغة تلميح من النوع البديل ، فلا توجد طريقة لإعادة تعيين رمز القولون المميز.
• يستخدم extends للفصل الموروث (كما تعلم). هذه صيغة شائعة جدًا في اللغات الأخرى ، وجميع الوثائق والبرامج التعليمية تتبع هذه الطريقة بالفعل. لن يكون هناك حافز قوي للابتعاد عن هذا وإنشاء المزيد من العمل لأسباب تجميلية بحتة.

group(MyHeader, "res://icon.png")

ليس من الواضح بالنسبة لي ما الذي سيفعله هذا. أعني ، يبدو أنه ستتم إضافة العقدة إلى مجموعة "MyHeader" (وهو ما قد يكون منطقيًا) ، ولكن ما هي هذه الأيقونة؟ المجموعات ليس لديها رموز مرتبطة بها.

export var my_property : Array(int) setget _set_my_property, _get_my_property # : replaces export type

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

onready export(NodePath) var the_node = get_node(the_node)

var test = 0 # no need for onready. variables declared outside of _ready automatically try to be onready vars

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

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

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

تحرير: لاحظ C # كسمات تسمح لك بدمجها على هذا النحو ..
[Attribute1(), Attribute2()]
ومع ذلك ، في حين أن هذا قد يساعد في تقليل عدد الخطوط ، إلا أنه لا يزال قبيحًا بعض الشيء

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

Calinou أعتقد أنه يجب ترك gdscript كما هي إذا لم يستطع الناس التنازل.
1 - يكسر التوافق مع الإصدارات السابقة دون داع
2 - يقوم بإنشاء ملفات أكبر وأكواد أقل قابلية للقراءة
3 - يجبر الناس على التغيير إلى نظام جديد لم يعتادوا عليه.
4 - يجبر الناس على استخدام نظام قد لا يرغبون فيه

1 - يكسر التوافق مع الإصدارات السابقة دون داع
2 - يقوم بإنشاء ملفات أكبر وأكواد أقل قابلية للقراءة
3 - يجبر الناس على التغيير إلى نظام جديد لم يعتادوا عليه.
4 - يجبر الناس على استخدام نظام قد لا يرغبون فيه

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

_تعديل: يمكننا أيضًا توفير أداة تحويل تلقائية على ما أعتقد.

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

groud هذا يستخدم التعليقات التوضيحية لأشياء غير ضرورية
1 - لماذا نحتاج إلى إهمال شيء يعمل؟
2 - يكون أقل قابلية للقراءة إذا كان عليك التمرير لأسفل 5 أسطر لرؤية الحقل

• تصدير هي في الأساس كلمة رئيسية عامة للمحرر
• على استعداد هو في الأساس إعلان var قبل تشغيل البرنامج النصي

كلاهما غير مناسب ليكونا تعليقات توضيحية

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

groud هذا يستخدم التعليقات التوضيحية لأشياء غير ضرورية

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

1 - لماذا نحتاج إلى إهمال شيء يعمل؟

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

2 - يكون أقل قابلية للقراءة إذا كان عليك التمرير لأسفل 5 أسطر لرؤية الحقل

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

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

تصدير هي في الأساس كلمة رئيسية عامة للمحرر
على استعداد هو في الأساس إعلان var قبل تشغيل البرنامج النصي
كلاهما غير مناسب ليكونا تعليقات توضيحية

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

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

<strong i="7">@onready</strong> var my_sprite = $Sprite
@onready; var my_sprite = $Sprite


@export_hint_string("Attack,Defense")
@export_hint(ENUM) export var my_enum : int = 0

@export_hint_string("Attack,Defense")
@export_hint(ENUM); export var my_enum : int = 0


<strong i="8">@export_hint_string</strong> "Attack,Defense";
<strong i="9">@export_hint</strong> ENUM export var my_enum : int = 0

<strong i="10">@export_hint_string</strong> "Attack,Defense"
<strong i="11">@export_hint</strong> ENUM; export var my_enum : int = 0


<strong i="12">@export</strong> type=String hint=MULTILINE; var my_text = ""

# more options

@export(type = String, hint = MULTILINE) var my_text = ""
@export(type = String, hint = MULTILINE); var my_text = ""

@export(String, hint = MULTILINE) var my_text = ""

# I personally prefer this one (positional and named args supported, default/optional args too)
@export(String, MULTILINE) var my_text = ""
@export(String, hint = MULTILINE) var my_text = ""
@export(type = String, hint = MULTILINE) var my_text = ""
@export(int, ENUM, "Attack,Defense") var my_enum:= 0

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

هذا هو رأي رفاقك.
أنا شخصياً أعتقد أن @ قبيح

تعديل:
فكيف سيعمل إعلان الأعضاء؟
القيام بذلك سيكون أمرًا مروعًا

<strong i="10">@description</strong> "Adds two numbers and returns the result."
<strong i="11">@parameter</strong> name=num1 type=float description="The first number"
<strong i="12">@parameter</strong> name=num2 type=float description="The second number"
<strong i="13">@returns</strong> type=float description="num1 and num2 added together"
func add(num1, num2):
    return num1 + num2

ما لم يكن من الممكن تصغيره من بداية @description إلى بداية func

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

func add(num1: float, num2: float) -> float: return num1 + num2

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

أنا شخصياً أعتقد أن @ قبيح
فكيف سيعمل إعلان الأعضاء؟
القيام بذلك سيكون أمرًا مروعًا

في اللغات الأخرى ، عادةً ما يقدم هذا الغرض التعليقات ، وليس التعليقات التوضيحية وعادةً ما تكون متساوية أو مطولة أكثر مما تم اقتراحه. في عائلة لغة C (اللغات الأكثر شيوعًا) ، يعد @ شائعًا جدًا للتعليقات التوضيحية (مثل Java و JavaScript و TypeScript و Scala وما قرأت Python أيضًا).

TypeScript (أعتقد أن الأنواع الموجودة في المستندات غير مطلوبة ويمكن للأدوات استخدام الأنواع الفعلية):

/** Adds two numbers and returns the result.
 * <strong i="16">@param</strong> num1 {float} The first number
 * <strong i="17">@param</strong> num2 {float} The second number
 * <strong i="18">@return</strong> {float} num1 and num2 added together
  **/
const add = (num1: number, num2: number): number => num1 + num2;

نكهة تشبه func:

@description("Adds two numbers and returns the result.")
@parameter(num1, "The first number", type=float)
@parameter(num2, "The second number", type=float)
@returns("num1 and num2 added together", type=float)
func add(num1: float, num2: float) -> float:
    return num1 + num2

بدون أنواع مكررة:

@description("Adds two numbers and returns the result.")
@parameter(num1, "The first number")
@parameter(num2, "The second number")
@returns("num1 and num2 added together")
func add(num1: float, num2: float) -> float:
    return num1 + num2

نكهة خالية من البارين:

<strong i="28">@description</strong> "Adds two numbers and returns the result."
<strong i="29">@parameter</strong> num1 "The first number"
<strong i="30">@parameter</strong> num2 "The second number"
<strong i="31">@returns</strong> "num1 and num2 added together"
func add(num1: float, num2: float) -> float:
    return num1 + num2

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

لقد استخدمت أسماء التعليقات التوضيحية من المثال السابق ، يمكن أن يكون @parameter ببساطة @param كما هو الحال في اللغات الأخرى ، ويمكن أن يكون @desc @description @desc ، @descr أو @func .

في GodoDoc ، أستخدم بناء جملة يعتمد على TypeScript (TypeDoc الذي يعتمد في حد ذاته على JSDoc و Javadoc) ، وفي رأيي ، يبدو أنه يعمل بشكل جيد:

## Same as [[bool_]], but `on_false`/`on_true` are functions.
## Only selected function will be called and its return value will be returned from `bool_lazy`.
## <strong i="44">@typeparam</strong> T {any} Return type
## <strong i="45">@param</strong> cond {bool} Condition
## <strong i="46">@param</strong> on_false {FuncLike<T>} Function to call and return its result when `cond` is `false`
## <strong i="47">@param</strong> on_true {FuncLike<T>} Function to call and return its result when `cond` is `true`
## <strong i="48">@return</strong> {T}
func bool_lazy_(cond: bool, on_false, on_true): return GGI.bool_lazy_(cond, on_false, on_true)
var bool_lazy = funcref(self, "bool_lazy_")

ما لم يكن من الممكن تصغيرها من بداية description إلى بداية func

نعم ، سيكون الطي عمومًا وخيارات الطي الافتراضي إضافة رائعة إلى المحرر (الطي بناءً على نوع الكتلة ، على سبيل المثال ، يمكنك تمكين في الإعدادات التي ستنهار الفئات الداخلية افتراضيًا).

أحب القدرة على وضع تعليق توضيحي في المقدمة أو أعلى ، لذلك فإن @annotation(a, b) رائع ، مع وجود أقواس اختيارية إذا لم يتم تقديم معلمات. تتيح القدرة على وضع المقدمة نفس سرعة الكتابة مثل الكلمات الرئيسية الحالية ، نظرًا لأن export و onready شائعان جدًا مع الخصائص.

ولكن فيما يتعلق بالاستخدام ، فأنا لا أحب التوثيق أيضًا. لقد اعتدت على التعليقات التوضيحية التي لها تأثير على البرنامج (حتى لو كانت غير مباشرة) ، في حين أن الوثائق غالبًا ما تضاعف مقدارها ثلاث مرات للاستخدام الشبيه بالتعليق ، ثم تظهر في كل مكان وتبرز نفس التعليقات التوضيحية الوظيفية ... فهي غير مناسبة لشيء ما هذا في كل مكان. في الأساس ، أحب استخدام التعليقات التوضيحية نفسها التي يمكن العثور عليها في C # ، مما يؤدي إلى الحاجة إلى كتابة عدد أقل بكثير من التعليقات التوضيحية أعلى الأعضاء (فهي نادرة جدًا في العادة ، ولا يتعين على الجميع كتابة 5 سطور كما أوضحت بعض الأمثلة) . إذا كان الجدل يدور حول عدم وجود واجهة برمجة تطبيقات لـ Godot لتحديد مستندات البرنامج النصي ، فهذه هي المشكلة ، ولا يجب حلها فقط من خلال التعليقات التوضيحية IMO. على الأقل ، أعتقد أنه يمكن للمرء استخدام ذلك اختياريًا ، لكنني لا أريد أن أجبر على القيام بذلك بهذه الطريقة ، وهو ما أجده غير مناسب للتوثيق الشامل. (إلى جانب ذلك ، فإن البرامج النصية ليست فقط GDScript ، كما أن حالة استخدام _get_property_list تجعل هذا الأمر أكثر صعوبة)

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

# No parenthesis when there are no parameters
<strong i="6">@export</strong> var myvar
# With parenthesis for parameters
@export(ENUM, "Up,Down,Left,Right") var myvar2
# Being able to write the annoation on the line before
@export(ENUM, "Up,Down,Left,Right") 
var myvar2

فيما يتعلق بجزء التوثيق ، سأبسط بناء الجملة أكثر (مع أخذ

<strong i="11">@description</strong> "Adds two numbers and returns the result."
<strong i="12">@parameter</strong> "The first number" # No need to name the args if they are ordered
<strong i="13">@parameter</strong> "The second number"
<strong i="14">@returns</strong> "num1 and num2 added together"
func add(num1: float, num2: float) -> float:
    return num1 + num2

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

الربط من أجل الصلة بالموضوع: godotengine / godot-plans # 177

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

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

بخصوص الكلمة الرئيسية onready وقيودها.

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

func explode():
    var bomb = preload("res://explosion.tscn").instance()
    # Oops, forgot to `add_child(bomb)` earlier
    bomb.fuse.wait_time = 5.0 # ERROR: fuse is `null`
    add_child(bomb)
    # ... because `fuse` is a $Timer node 
    # which is only initialized once added to the scene tree.

بالطبع تحتاج إلى add_child() المشهد المتطور قبل محاولة تعيين fuse ، ولكن ماذا لو احتاجت العقد / الكائنات الأخرى إلى أن تكون على دراية بالفتيل الدقيق قبل إضافة المشهد إلى شجرة المشهد ؟

بعد مرور بعض الوقت ، وجدت حلاً كما هو موضح في https://github.com/godotengine/godot/issues/33620#issuecomment -559999681. كما قد تلاحظ هناك ، فإن onready هو فقط NOTIFICATION_READY ، بينما ما أحتاجه بالفعل هو NOTIFICATION_INSTANCED وقمت بتهيئة مراجعي حتى قبل ذلك. المشكلة الوحيدة هي أنه لا توجد كلمة رئيسية oninstanced ، وأعتقد أنك قد تكتشف ما أقصده. 🙂

لذلك ، أعتقد أنه سيكون من الجيد إعادة إنشاء الكلمة الرئيسية onready كتعليق توضيحي بالفعل ، مع دعم بعض الحالات الأخرى (مثل حالتي ، كما هو الحال دائمًا!) بوظيفة @oninstanced بدون تضخيم لغة البرمجة ، بالإضافة إلى إضافة دعم للإشعارات الأخرى المتعلقة بالتهيئة ( _init ، _enter_tree ، إلخ).

الاقتراح ذو الصلة: godotengine / godot- مقترحات # 260.

تم فتح عرض بمزيد من التفاصيل المحددة: https://github.com/godotengine/godot-proposals/issues/828

حلت محلها الاقتراح أعلاه.