ما هو كود التوثيق الذاتي وهل يمكن أن يحل محل الكود الموثق جيدًا؟[مغلق]

Question

لدي زميل يصر على أن الكود الخاص به لا يحتاج إلى تعليقات، فهو "توثيق ذاتي".

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

مساعدتي على فهم له وجهة نظر.

• ما هو كود التوثيق الذاتي
• هل يمكن حقًا أن يحل محل التعليمات البرمجية الموثقة والمعلقة جيدًا
• هل هناك مواقف يكون فيها ذلك أفضل من التعليمات البرمجية الموثقة جيدًا والتعليق عليها
• هل هناك أمثلة حيث لا يمكن أن يكون الكود موثقًا ذاتيًا بدون تعليقات

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

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

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

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

Answer 1

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

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

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

Answer 2

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

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

إلى رمز التوثيق الذاتي هذا، والذي يظهر ماذا يتم انجازه:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

ثم إلى هذا الكود الموثق الذي يوضح بشكل أفضل لماذا يتم القيام به:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

والنسخة النهائية من الكود كوثائق بدون تعليقات مطلوبة:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

فيما يلي مثال على أسلوب التعليق السيئ:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

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

Answer 3

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

Answer 4

قال أحدهم ذات مرة

1) اكتب فقط التعليقات على التعليمات البرمجية التي يصعب فهمها.
2) حاول ألا تكتب تعليمات برمجية يصعب فهمها.

Answer 5

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

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

Answer 6

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

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

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

Answer 7

نسيت من أين حصلت على هذا، ولكن:

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

Answer 8

يعد رمز التوثيق الذاتي مثالًا جيدًا على "DRY" (لا تكرر نفسك).لا تكرر المعلومات الموجودة في التعليقات الموجودة أو التي يمكن أن تكون موجودة في الكود نفسه.

بدلاً من شرح الغرض من استخدام المتغير، قم بإعادة تسمية المتغير.

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

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

إلخ.

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

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

Answer 9

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

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

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

Answer 10

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

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

print "Hello, World!"

وهذا هو الحال:

factorial n = product [1..n]

وهذا هو الحال:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

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

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

Answer 11

مرتب:

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

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

Answer 12

أولاً، خذ بعين الاعتبار المقتطف التالي:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

لو كان الأمر كذلك، لكان الإصدار الأفضل هو:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

Answer 13

عندما تقرأ "رمز التوثيق الذاتي" ، ترى ما يفعله ، لكن لا يمكنك دائما تخمين سبب عملها بهذه الطريقة بالذات.

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

عندما تقوم بالصيانة، تصبح هذه المعلومات الخلفية مهمة جدًا.

رشة ملح فقط..

Answer 14

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

Answer 15

هل سمعت عن مشروع "WEB" الخاص بدونالد كنوث لتنفيذ مشروعه البرمجة الأدبية مفهوم؟إنه أكثر من مجرد كود للتوثيق الذاتي؛إنها أشبه بالوثائق التي يمكن تجميعها وتنفيذها كرمز.لا أعرف مقدار استخدامه اليوم بالرغم من ذلك.

Answer 16

الفرق هو بين "ماذا" و"كيف".

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

Answer 17

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

"قم بتوثيق الكود الخاص بك وكأن الشخص الذي يحتفظ به هو مهووس بالقتل ويعرف المكان الذي تعيش فيه."

Answer 18

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

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

Answer 19

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

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

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

Answer 20

أنا مندهش أنه لم يقم أحد بذلك "البرمجة الأدبية"، وهي تقنية تم تطويرها في عام 1981 بواسطة دونالد إي.Knuth of TeX وشهرة "فن برمجة الكمبيوتر".

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

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

لقد وجدت مثالا على شبكة الإنترنت منه: http://moonflare.com/code/select/select.nw أو نسخة HTML http://moonflare.com/code/select/select.html

إذا تمكنت من العثور على كتاب كنوث في المكتبة (Donald E.كنوث، برمجة القراءة والكتابة، ستانفورد، كاليفورنيا:مركز دراسة اللغة والمعلومات، 1992، CSLI Lecture Notes، no.27.) يجب عليك قراءتها.

هذا كود التوثيق الذاتي، كامل مع المنطق وكل شيء.حتى يجعل وثيقة لطيفة ، كل شيء آخر هو مجرد تعليقات مكتوبة بشكل جيد :-)

Answer 21

وجهة نظري مكتوبة في هذا المنشور:

النصيحة الوحيدة لتوثيق التعليمات البرمجية الخاصة بك.

مقتطفات:

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

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

Answer 22

أود أن أقدم وجهة نظر أخرى للعديد من الإجابات الصحيحة:

ما هو كود المصدر؟ما هي لغة البرمجة؟

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

هل يجب أن تكون قادرًا على قراءة ما تكتبه؟

كود المصدر غير مكتوب باللغة البشرية.لقد تم تجربتها (على سبيل المثال FORTRAN) ولكنها لم تكن ناجحة تمامًا.

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

تحتوي معظم لغات البرمجة على تكرار حتى يتمكن المترجم من اللحاق بنا عندما لا نكون متماسكين.تستخدم اللغات الأخرى المزيد من الاستدلال وتحاول التخلص من هذا التكرار.

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

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

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

Answer 23

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

بالنسبة لي، هذه هي القواعد التي أحاول اتباعها:

• يجب أن يكون الرمز سهلا وواضحا اقرأ قدر الإمكان.
• يجب أن تعطي التعليقات أسبابا ل قرارات التصميم التي اتخذتها ، مثل:لماذا هل أستخدم هذه الخوارزمية ، أو القيود التي تحتوي عليها الشفرة ، مثل:هل لا تعمل عندما ...(يجب أن يكون هذا التعامل معها في عقد / تأكيد في الرمز) (عادة ضمن الوظيفة / الإجراء).
• يجب أن تسرد الوثائق الاستخدام (استدعاء الاحتكاكات) ، الجانب الآثار ، قيم الإرجاع المحتملة.إنه يمكن استخراجها من التعليمات البرمجية باستخدام أدوات مثل jDoc أو xmlDoc.إنه لذلك عادة ما يكون خارج الوظيفة / الإجراء ، ولكن بالقرب من رمز يصفه.

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

Answer 24

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

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

إن القدرة على تحديد أن الكود يفعل X من نظرة سريعة هو أسهل بكثير من القدرة على تحديد أن الكود لا يفعل Y.عليه توثيق Y...

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

Answer 25

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

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

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

Answer 26

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

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

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

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

Answer 27

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

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

Answer 28

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

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

Answer 29

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

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

BisectionSearch

بحث ثنائي

BinaryChop

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

Answer 30

بالنسبة لي، قراءة التعليمات البرمجية التي تحتاج إلى تعليقات هي بمثابة قراءة نص باللغة التي لا أعرفها.أرى البيان ولا أفهم ماذا يفعل أو لماذا - ويجب أن ألقي نظرة على التعليقات.قرأت عبارة وأحتاج إلى البحث في القاموس لفهم معناها.

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

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

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

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