CodeGym /مدونة جافا /Random-AR /قواعد الترميز: قوة الأسماء الصحيحة والتعليقات الجيدة والس...
John Squirrels
مستوى
San Francisco

قواعد الترميز: قوة الأسماء الصحيحة والتعليقات الجيدة والسيئة

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

الأسماء الصحيحة

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

من المسلسل التلفزيوني "شيرلوك" (2010-2017)

واجهات التسمية

عادةً ما تحتوي الواجهات على أسماء تبدأ بحرف كبير ومكتوبة بلغة CamelCase. عند كتابة واجهة، كان من الممارسات الجيدة إضافة البادئة "I" لتعيينها كواجهة (على سبيل المثال، IUserService)، ولكن هذا يبدو قبيحًا جدًا ومشتتًا للانتباه. في مثل هذه الحالات، من الأفضل حذف البادئة (UserService) وإضافة "Impl" كلاحقة لاسم تنفيذها (على سبيل المثال UserServiceImpl). أو ربما، كملاذ أخير، قم بإضافة بادئة "C" إلى اسم التنفيذ (على سبيل المثال، CUserService).

أسماء الفصول

تمامًا مثل الواجهات، تتم كتابة أسماء الفئات بأحرف كبيرة وتستخدم CamelCase. لا يهم إذا كنا نواجه نهاية العالم من الزومبي، ولا يهم إذا كانت النهاية في متناول اليد - أبدًا، أبدًا، لا ينبغي أبدًا أن يكون اسم الفصل فعلًا! يجب أن تكون أسماء الفئات والكائنات أسماء أو أسماء مركبة (UserController، وUserDetails، وUserAccount، وما إلى ذلك). يجب ألا تضع اختصار التطبيق في نهاية اسم كل فئة، لأن ذلك لن يؤدي إلا إلى إضافة تعقيد غير ضروري. على سبيل المثال، إذا كان لدينا تطبيق لترحيل بيانات المستخدم، فيرجى عدم إضافة "UDM" إلى كل فئة، مثل UDMUserDetails، وUDMUserAccount، وUDMUserController.

أسماء الطريقة

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

أسماء متغيرة

في معظم الحالات، تبدأ أسماء المتغيرات بحرف صغير وتستخدم أيضًا CamelCase، إلا عندما يكون المتغير ثابتًا عامًا. في مثل هذه الحالات، تتم كتابة جميع أحرف الاسم بأحرف كبيرة ويتم فصل الكلمات بشرطة سفلية ("_"). للراحة، يمكنك استخدام سياق ذي معنى عند تسمية المتغيرات. بمعنى آخر، عند وجود متغير كجزء من شيء أكبر، على سبيل المثال، الاسم الأول أو الاسم الأخير أو الحالة. في مثل هذه الحالات، يمكنك إضافة بادئة تشير إلى الكائن الذي ينتمي إليه هذا المتغير. على سبيل المثال: userFirstName، userLastName، userStatus. يجب عليك أيضًا تجنب الأسماء المتشابهة للمتغيرات عندما يكون لها معاني مختلفة تمامًا. فيما يلي بعض المتضادات التي يتم مواجهتها بشكل متكرر والمستخدمة في أسماء المتغيرات:
  • البدء/النهاية
  • اول الاخر
  • مقفل / مقفلة
  • الحد الأدنى - الحد الأقصى
  • السابق التالي
  • قديم / جديد
  • مفتوح/مغلق
  • مرئي غير مرئي
  • المصدر/الهدف
  • جهة المصدر
  • فوق تحت

أسماء المتغيرات القصيرة

عندما يكون لدينا متغيرات مثل x أو n أو شيء من هذا القبيل، فإننا لا نرى على الفور نية الشخص الذي كتب الكود. ليس من الواضح ما يفعله n. يتطلب اكتشاف ذلك تفكيرًا أكثر دقة (وهذا يعني الوقت، الوقت، الوقت). على سبيل المثال، لنفترض أن لدينا حقلاً يمثل معرف المستخدم المسؤول. بدلاً من اسم متغير مثل x أو ببساطة id، سوف نسمي هذا المتغير "responsibleUserId"، مما يؤدي على الفور إلى تحسين سهولة القراءة ومحتوى المعلومات. ومع ذلك، فإن الأسماء القصيرة مثل n لها مكان كمتغيرات محلية في الطرق الصغيرة، حيث تكون كتلة التعليمات البرمجية التي تتضمن هذا المتغير مجرد سطرين طويلين، ويصف اسم الطريقة تمامًا ما يحدث هناك. عند رؤية مثل هذا المتغير، يفهم المطور أنه ذو أهمية ثانوية وله نطاق محدود للغاية. ونتيجة لذلك، فإن النطاق له اعتماد معين على طول اسم المتغير: كلما كان الاسم أطول، كلما كان المتغير أكثر عمومية والعكس صحيح. على سبيل المثال، إليك طريقة للعثور على آخر مستخدم تم حفظه حسب التاريخ:
public User findLastUser() {
   return findAllUsers().stream()
           .sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
           .findFirst()
           .orElseThrow(() -> new ResourceNotFoundException("No user exists"));
}
هنا نستخدم المتغيرات ذات الأسماء المختصرة x وy لفرز الدفق، ثم ننساها.

الطول الأمثل

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

اختلافات صغيرة

ولا يسعني إلا أن أذكر الاختلافات الدقيقة في الأسماء. وهذه أيضًا ممارسة سيئة، نظرًا لأن هذه الاختلافات يمكن أن تكون مربكة ببساطة أو تتطلب قضاء الكثير من الوقت الإضافي لملاحظةها. على سبيل المثال، من الصعب اكتشاف الفرق بين InvalidDataAccessApiUsageException وInvalidDataAccessResourceUsageException بنظرة واحدة. قد يحدث أيضًا ارتباك في كثير من الأحيان عند استخدام الأحرف الصغيرة L وO، لأنه من السهل الخلط بينهما وبين 1 و0. في بعض الخطوط يكون الفرق أكثر وضوحًا، وفي البعض الآخر يكون الفرق أقل.

المعنى

نحن بحاجة إلى جعل الأسماء ذات معنى، ولكن لا نخلق الغموض من خلال المرادفات، حيث أن UserData وUserInfo، على سبيل المثال، لهما نفس المعنى بالفعل. في هذه الحالة، سيتعين علينا التعمق في الكود لفهم الكائن المحدد الذي نحتاجه. تجنب الكلمات التي لا تنقل معلومات مفيدة. على سبيل المثال، في firstNameString، لماذا نحتاج إلى كلمة String؟ هل يمكن أن يكون هذا كائنًا للتاريخ حقًا؟ بالطبع لا. لذلك، نحن ببساطة نستخدم الاسم الأول. أود أيضًا أن أذكر المتغيرات المنطقية. على سبيل المثال، خذ قيمة منطقية تسمى flagDeleted. كلمة العلم ليس لها معنى. من المعقول أن نسميها محذوفة.

التضليل

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

يبحث

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

تعليقات

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

أنواع التعليقات

  • التعليقات القانونية — التعليقات في بداية كل ملف مصدر لأسباب قانونية، على سبيل المثال:

    * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
    * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  • التعليقات الإعلامية — التعليقات التي تمثل شرحًا للكود (توفير معلومات إضافية أو شرح الغرض من قسم معين من الكود).

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

    /*
    * Combines the user from the database with the one passed for updating
    * When a field in requestUser is empty, it is filled with old data from foundUser
    */
    private User mergeUser(User requestUser, User foundUser) {
           return new User(
           foundUser.getId(),
           requestUser.getFirstName() == null ? requestUser.getFirstName() : foundUser.getFirstName(),
           requestUser.getMiddleName() == null ? requestUser.getMiddleName() : foundUser.getMiddleName(),
           requestUser.getLastName() == null ? requestUser.getLastName() : foundUser.getLastName(),
           requestUser.getAge() == null ? requestUser.getAge() : foundUser.getAge()
           );
           }

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

  • التعليقات التحذيرية - تعليق يهدف إلى تحذير المطورين الآخرين بشأن العواقب غير المرغوب فيها لأي إجراء (على سبيل المثال، تحذيرهم حول سبب وضع علامة @Ignore على الاختبار):

    // Takes too long to run
    // Don't run if you don't have a lot of time
    @Ignore
    @Test
    public void someIntegrationTest() {
           ……
           }

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

    على سبيل المثال سيكون:

    // TODO: Add a check for the current user ID (when the security context is created)
    
    @Override
    public Resource downloadFile(File file) {
           return fileManager.download(file);
           }

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

  • تعزيز التعليقات - التعليقات التي تؤكد على أهمية الظرف الذي قد يبدو للوهلة الأولى غير ذي أهمية.

    على سبيل المثال، فكر في جزء من الطريقة التي تملأ قاعدة بيانات اختبارية ببعض البرامج النصية:

    Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8)
           .trim()
           .split(";"))
           .forEach(jdbcTemplate::update);
    // The trim() call is very important. It removes possible spaces at the end of the script
    // so that when we read and split into separate requests, we don't end up with empty ones

  • تعليقات Javadoc — التعليقات التي تصف واجهة برمجة التطبيقات (API) لوظائف معينة. من المحتمل أن تكون هناك التعليقات الأكثر فائدة، نظرًا لأن واجهة برمجة التطبيقات الموثقة أسهل بكثير في العمل معها. ومع ذلك، يمكن أيضًا أن تكون قديمة مثل أي نوع آخر من التعليقات. لذا، لا تنس أبدًا أن المساهمة الرئيسية في التوثيق لا تتم من خلال التعليقات، بل من خلال التعليمات البرمجية الجيدة.

    فيما يلي مثال لطريقة شائعة إلى حد ما لتحديث المستخدم:

    /**
    * Updates the passed fields for a user based on its id.
         *
    * @param id id of the user to be updated
    * @param user user with populated fields for updating
    * @return updated user
    */
           User update(Long id, User user);

تعليقات سيئة

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

    خذ بعين الاعتبار هذا المثال:

    public void configureSomeSystem() {
           try{
           String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE);
           FileInputStream stream = new FileInputStream(configPath);
           } catch (FileNotFoundException e) {
           // If there is no configuration file, the default configuration is loaded
          }
    }

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

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

    دعونا نرى مثالا:

    public class JdbcConnection{
    public class JdbcConnection{
       /**
        * The logger associated with the current class
        */
       private Logger log = Logger.getLogger(JdbcConnection.class.getName());
    
       /**
        * Creates and returns a connection using the input parameters
        */
       public static Connection buildConnection(String url, String login, String password, String driver) throws Exception {
           Class.forName(driver);
           connection = DriverManager.getConnection(url, login, password);
           log.info("Created connection with db");
           return connection;
       }

    ما الفائدة من مثل هذه التعليقات؟ كل ما يشرحونه واضح تمامًا بالفعل.

  • التعليقات غير الموثوقة — التعليقات غير الصحيحة والمضللة فقط (معلومات مضللة). على سبيل المثال، هنا واحد.

    /**
    * Helper method. Closes the connection with the scanner if isNotUsing is true
    */
    private void scanClose(Scanner scan, boolean isNotUsing) throws Exception {
       if (!isNotUsing) {
           throw new Exception("The scanner is still in use");
       } scan.close();
    }

    ما هو الخطأ في هذا التعليق؟ والحقيقة أنها تكذب علينا قليلاً، حيث يتم إغلاق الاتصال إذا كان isNotUsing خطأً، وليس العكس، كما يخبرنا التعليق.

  • التعليقات الإجبارية — التعليقات التي تعتبر إلزامية (مثل تعليقات Javadoc)، ولكنها في الواقع تتراكم بشكل مفرط في بعض الأحيان وغير موثوقة وغير ضرورية (تحتاج إلى التفكير فيما إذا كانت هذه التعليقات مطلوبة بالفعل).

  • مثال:

    /**
    * Create a user based on the parameters
    * @param firstName first name of the created user
    * @param middleName middle name of the created user
    * @param lastName last name of the created user
    * @param age age of the created user
    * @param address address of the created user
    * @return user that was created
    */
    User createNewUser(String firstName, String middleName, String lastName, String age, String address);

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

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

    /**
    * Records kept since January 9, 2020;
    **********************************************************************
    * 9 Jan 2020: Providing a database connection using JDBC Connection;
    * 15 Jan 2020: Adding DAO-level interfaces for working with the database;
    * 23 Jan 2020: Adding integration tests for the database;
    * 28 Jan 2020: Implementation of DAO-level interfaces;
    * 1 Feb 2020: Development of interfaces for services,
    * in accordance with the requirements specified in user stories;
    * 16 Feb 2020: Implementation of service interfaces
    * (implementation of business logic related to the work of the database);
    * 25 Feb 2020: Adding tests for services;
    * 8 Mar 2020: Celebration of International Women's Day (Terry is drunk again);
    * 21 Mar 2020: Refactoring the service layer;
    */

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

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

    * @author Bender Bending

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

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

    //    public void someMethod(SomeObject obj) {
    //    .....
    //    }

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

  • التعليقات غير الواضحة — التعليقات التي تصف شيئًا ما بطريقة معقدة للغاية.

    /*
        * Start with an array large enough to store
        * all the data bytes (plus filter bytes) with a cushion, plus 300 bytes
        * for header data
        */
    this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];

    يجب أن يشرح التعليق الكود. ولا ينبغي أن يحتاج في حد ذاته إلى تفسير. إذن ما هو الخطأ هنا؟ ما هي "بايتات التصفية"؟ ما هو كل هذا "+1"؟ لماذا بالضبط 300؟

إذا كنت قد قررت بالفعل كتابة التعليقات، فإليك بعض النصائح:
  1. استخدم الأنماط التي يسهل الحفاظ عليها: الحفاظ على الأنماط الفاخرة والغريبة أمر مزعج ويستغرق وقتًا طويلاً.
  2. لا تستخدم تعليقات نهاية السطر التي تشير إلى أسطر مفردة: فالنتيجة هي كومة كبيرة من التعليقات. علاوة على ذلك، من الصعب التفكير في تعليق ذي معنى لكل سطر.
  3. عندما تكتب تعليقًا، حاول الإجابة على السؤال "لماذا"، وليس "كيف".
  4. تجنب المعلومات المختصرة. كما قلت أعلاه، لا نحتاج إلى تفسير للتعليق: التعليق نفسه هو التفسير.
  5. يمكنك استخدام التعليقات لتدوين الوحدات ونطاقات القيم.
  6. ضع التعليقات بالقرب من الكود الذي يصفونه.
أخيرًا، ما زلت أريد أن أذكرك بأن أفضل تعليق هو عدم التعليق، بل استخدام التسمية الماهرة في جميع أنحاء تطبيقك. كقاعدة عامة، سنعمل في معظم الأوقات باستخدام التعليمات البرمجية الموجودة، وصيانتها وتوسيعها. يكون الأمر أكثر ملاءمة عندما يكون هذا الرمز سهل القراءة والفهم، لأن الكود السيئ يمثل عقبة. إنه مثل رمي مفتاح في العمل، والعجلة هي رفيقها الأمين. وكلما زاد سوء الكود لدينا، انخفض الأداء. وهذا يعني أننا بحاجة إلى إعادة البناء من وقت لآخر. ولكن إذا حاولت منذ البداية كتابة تعليمات برمجية لا تتسبب في رغبة المطورين التاليين في العثور عليك وقتلك، فلن تحتاج إلى إعادة هيكلتها كثيرًا. ولكنه سيظل ضروريًا، نظرًا لأن شروط المنتج ومتطلباته تتغير باستمرار مع إضافة تبعيات واتصالات جديدة. حسنا، أعتقد أن هذا كل شيء بالنسبة لي اليوم. شكرا لكل من قرأ هذا الحد :)
تعليقات
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION