AOSP Java Code Style للمساهمين

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

كن متسقا

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

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

قواعد لغة جافا

يتبع Android اصطلاحات ترميز Java القياسية مع القواعد الإضافية الموضحة أدناه.

لا تتجاهل الاستثناءات

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

  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) { }
  }

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

" في أي وقت يكون لدى شخص ما شرط فارغ يجب أن يكون لديه شعور مخيف. هناك بالتأكيد أوقات يكون فيها هذا هو الشيء الصحيح الذي يجب فعله ، ولكن على الأقل عليك التفكير فيه. في Java لا يمكنك الهروب من الشعور المخيف. "- جيمس جوسلينج

البدائل المقبولة (بترتيب الأفضلية) هي:

  • ارمِ الاستثناء لمتصل طريقتك.
      void setServerPort(String value) throws NumberFormatException {
          serverPort = Integer.parseInt(value);
      }
    
  • قم بطرح استثناء جديد يتناسب مع مستوى تجريدك.
      void setServerPort(String value) throws ConfigurationException {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new ConfigurationException("Port " + value + " is not valid.");
        }
      }
    
  • تعامل مع الخطأ بأمان واستبدل قيمة مناسبة في كتلة catch {} .
      /** Set port. If value is not a valid number, 80 is substituted. */
    
      void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            serverPort = 80;  // default port for server
        }
      }
    
  • اكتشف الاستثناء وأطلق نسخة جديدة من RuntimeException . هذا أمر خطير ، لذا لا تفعل ذلك إلا إذا كنت متأكدًا من أنه في حالة حدوث هذا الخطأ ، فإن الشيء المناسب الذي يجب فعله هو التعطل.
      /** Set port. If value is not a valid number, die. */
    
      void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new RuntimeException("port " + value " is invalid, ", e);
        }
      }
    
  • كحل أخير ، إذا كنت واثقًا من أن تجاهل الاستثناء مناسب ، فيمكنك تجاهله ، ولكن يجب عليك أيضًا التعليق على السبب لسبب وجيه.
    /** If value is not a valid number, original port number is used. */
    
    void setServerPort(String value) {
        try {
            serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
            // Method is documented to just ignore invalid user input.
            // serverPort will just be unchanged.
        }
    }
    

لا تلتقط الاستثناءات العامة

قد يكون من المغري أن تكون كسولًا عند اكتشاف الاستثناءات والقيام بشيء من هذا القبيل:

  try {
      someComplicatedIOFunction();        // may throw IOException
      someComplicatedParsingFunction();   // may throw ParsingException
      someComplicatedSecurityFunction();  // may throw SecurityException
      // phew, made it all the way
  } catch (Exception e) {                 // I'll just catch all exceptions
      handleError();                      // with one generic handler!
  }

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

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

بدائل للقبض على الاستثناءات العامة:

  • التقط كل استثناء على حدة كجزء من كتلة الصيد المتعدد ، على سبيل المثال:
    try {
        ...
    } catch (ClassNotFoundException | NoSuchMethodException e) {
        ...
    }
  • أعد بناء الكود الخاص بك للحصول على معالجة أكثر دقة للأخطاء ، مع كتل محاولة متعددة. قسّم الإدخال / الإخراج من التحليل ، وتعامل مع الأخطاء بشكل منفصل في كل حالة.
  • إعادة طرح الاستثناء. في كثير من الأحيان لا تحتاج إلى التقاط الاستثناء في هذا المستوى على أي حال ، فقط دع الطريقة تطرحه.

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

لا تستخدم الصيغ النهائية

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

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

واردات مؤهلة بالكامل

عندما تريد استخدام class Bar من package foo ، فهناك طريقتان ممكنتان لاستيراده:

  • import foo.*;

    من المحتمل أن يقلل من عدد بيانات الاستيراد.

  • import foo.Bar;

    يوضح الفئات المستخدمة ويكون الرمز أكثر قابلية للقراءة للمشرفين.

استخدم import foo.Bar; لاستيراد جميع أكواد Android. هناك استثناء صريح لمكتبات Java القياسية ( java.util.* ، java.io.* ، إلخ.) ورمز اختبار الوحدة ( junit.framework.* ).

قواعد مكتبة جافا

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

قواعد أسلوب جافا

استخدم تعليقات جافادوك القياسية

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

/*
 * Copyright 2022 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Does X and Y and provides an abstraction for Z.
 */

public class Foo {
    ...
}

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

أمثلة

/** Returns the correctly rounded positive square root of a double value. */

static double sqrt(double a) {
    ...
}

أو

/**
 * Constructs a new String by converting the specified array of
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}

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

كل طريقة تكتبها ، عامة أو غير ذلك ، ستستفيد من Javadoc. الطرق العامة هي جزء من API وبالتالي تتطلب Javadoc. لا يفرض Android أسلوبًا محددًا لكتابة تعليقات Javadoc ، ولكن يجب عليك اتباع التعليمات الموجودة في كيفية كتابة تعليقات Doc لأداة Javadoc .

اكتب طرقًا قصيرة

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

تحديد الحقول في الأماكن القياسية

حدد الحقول إما في أعلى الملف أو مباشرة قبل الطرق التي تستخدمها.

تحديد نطاق متغير

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

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

الاستثناء هو عبارات try-catch. إذا تمت تهيئة متغير بقيمة الإرجاع للطريقة التي تطرح استثناءًا محددًا ، فيجب تهيئته داخل كتلة try. إذا كان يجب استخدام القيمة خارج كتلة try ، فيجب الإعلان عنها قبل كتلة try ، حيث لا يمكن تهيئتها بشكل معقول:

// Instantiate class cl, which represents some sort of Set

Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set
s.addAll(Arrays.asList(args));

ومع ذلك ، يمكنك تجنب هذه الحالة عن طريق تغليف كتلة try-catch بطريقة:

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set
Set s = createSet(cl);
s.addAll(Arrays.asList(args));

قم بتعريف متغيرات الحلقة في تعليمة for نفسها ما لم يكن هناك سبب مقنع للقيام بخلاف ذلك:

for (int i = 0; i < n; i++) {
    doSomething(i);
}

و

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}

بيانات طلب الاستيراد

طلب بيانات الاستيراد هو:

  1. واردات Android
  2. الواردات من جهات خارجية ( com ، junit ، net ، org )
  3. java javax

لمطابقة إعدادات IDE تمامًا ، يجب أن تكون عمليات الاستيراد:

  • أبجديًا داخل كل مجموعة ، بأحرف كبيرة قبل الأحرف الصغيرة (على سبيل المثال ، Z قبل a)
  • مفصولة بسطر فارغ بين كل مجموعة رئيسية ( android ، com ، junit ، net ، org ، java ، javax )

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

اخترنا هذا النمط مثل:

  • تميل الواردات التي يريد الأشخاص النظر إليها أولاً إلى أن تكون في الأعلى ( android ).
  • تميل الواردات التي يرغب الأشخاص في النظر إليها على الأقل إلى أن تكون في الأسفل ( java ).
  • يمكن للبشر بسهولة اتباع الأسلوب.
  • يمكن أن تتبع IDEs النمط.

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

استخدام المسافات للمسافات البادئة

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

نستخدم ثمانية (8) مسافات بادئة لالتفاف الأسطر ، بما في ذلك استدعاءات الوظائف والتعيينات.

مستحسن

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

لا ينصح

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

اتبع اصطلاحات تسمية الحقول

  • تبدأ أسماء الحقول غير العامة وغير الثابتة بـ m .
  • تبدأ أسماء الحقول الثابتة بـ s .
  • تبدأ الحقول الأخرى بحرف صغير.
  • الحقول النهائية الثابتة (الثوابت ، غير قابلة للتغيير بشدة) هي ALL_CAPS_WITH_UNDERSCORES .

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

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

استخدم نمط الدعامة القياسي

ضع الأقواس على نفس سطر الكود قبلهم ، وليس على السطر الخاص بهم:

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

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

if (condition) {
    body();
}

وهذا مقبول:

if (condition) body();

لكن هذا غير مقبول:

if (condition)
    body();  // bad!

حد طول الخط

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

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

استخدم شروح Java القياسية

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

ممارسات Android القياسية للتعليقات التوضيحية الثلاثة المحددة مسبقًا في Java هي:

  • استخدم التعليق التوضيحي @Deprecated عندما لا يُنصح باستخدام العنصر المشروح. إذا كنت تستخدم التعليق التوضيحي @Deprecated ، فيجب أن يكون لديك أيضًا علامة @deprecated Javadoc ويجب تسمية تطبيق بديل. بالإضافة إلى ذلك ، تذكر أنه لا يزال من المفترض أن تعمل طريقة @Deprecated . إذا رأيت رمزًا قديمًا يحتوي على علامة @deprecated Javadoc ، فأضف التعليق التوضيحي @Deprecated .
  • استخدم التعليق التوضيحي @Override عندما تتجاوز إحدى الطرق الإعلان أو التنفيذ من فئة فائقة. على سبيل المثال ، إذا كنت تستخدم علامة @inheritdocs Javadoc ، وتشتق من فئة (وليست واجهة) ، فيجب عليك أيضًا توضيح أن الطريقة تتجاوز طريقة الفئة الأصل.
  • استخدم التعليق التوضيحي @SuppressWarnings فقط في ظل ظروف يستحيل فيها حذف تحذير. إذا تجاوز التحذير اختبار "استحالة الحذف" ، فيجب استخدام التعليق التوضيحي @SuppressWarnings ، للتأكد من أن جميع التحذيرات تعكس المشكلات الفعلية في الكود.

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

    // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
    @SuppressWarnings("generic-cast")
    List<String> blix = Utility.rotate(blax);
    

    عندما يكون التعليق التوضيحي @SuppressWarnings مطلوبًا ، أعد تشكيل الكود لعزل عناصر البرنامج حيث ينطبق التعليق التوضيحي.

تعامل مع الاختصارات على أنها كلمات

تعامل مع الاختصارات والاختصارات ككلمات في تسمية المتغيرات والطرق والفئات لجعل الأسماء أكثر قابلية للقراءة:

جيد سيئة
طلب XmlHttp طلب XMLHTTP
getCustomerId getCustomerID
فئة Html فئة HTML
عنوان url للسلسلة سلسلة URL
معرف طويل معرف طويل

نظرًا لأن كلاً من قواعد كود JDK و Android غير متسقة حول الاختصارات ، فمن المستحيل عمليا أن تكون متسقة مع الكود المحيط. لذلك ، تعامل دائمًا مع الاختصارات على أنها كلمات.

استخدم تعليقات TODO

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

// TODO: Remove this code after the UrlTable2 has been checked in.

و

// TODO: Change this to use a flag instead of a constant.

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

سجل باعتدال

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

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

    يتم تسجيل هذا المستوى حتى عند إنشاءات الإصدار ، ويجب أن يكون محاطًا if (LOCAL_LOG) أو if LOCAL_LOGD) ، حيث يتم تحديد LOCAL_LOG[D] في الفصل الدراسي أو المكون الفرعي الخاص بك ، بحيث يكون هناك إمكانية لتعطيل كل عمليات التسجيل هذه . لذلك ، يجب ألا يكون هناك منطق نشط في كتلة if (LOCAL_LOG) . يجب أيضًا وضع كل سلسلة إنشاءات السجل داخل كتلة if (LOCAL_LOG) . لا تعيد تشكيل استدعاء التسجيل في استدعاء طريقة إذا كان سيتسبب في حدوث بناء السلسلة خارج كتلة if (LOCAL_LOG) .

    لا تزال هناك بعض التعليمات البرمجية التي لا تزال تشير if (localLOGV) . يعتبر هذا مقبولًا أيضًا ، على الرغم من أن الاسم غير قياسي.

  • VERBOSE : استخدمه لكل شيء آخر. يتم تسجيل هذا المستوى فقط عند إنشاءات تصحيح الأخطاء ويجب أن يكون محاطًا if (LOCAL_LOGV) (أو ما يعادلها) بحيث يمكن تجميعها بشكل افتراضي. يتم تجريد أي بناء سلسلة من تصميمات الإصدار ويحتاج إلى الظهور داخل كتلة if (LOCAL_LOGV) .

ملاحظات

  • ضمن وحدة نمطية معينة ، بخلاف مستوى VERBOSE ، يجب الإبلاغ عن الخطأ مرة واحدة فقط إن أمكن. ضمن سلسلة واحدة من استدعاءات الوظائف داخل وحدة نمطية ، يجب أن تقوم الوظيفة الداخلية فقط بإرجاع الخطأ ، ويجب على المتصلين في نفس الوحدة إضافة بعض التسجيل فقط إذا كان ذلك يساعد بشكل كبير في عزل المشكلة.
  • في سلسلة من الوحدات ، بخلاف مستوى VERBOSE ، عندما تكتشف وحدة المستوى الأدنى بيانات غير صالحة قادمة من وحدة مستوى أعلى ، يجب على الوحدة ذات المستوى الأدنى تسجيل هذا الموقف في سجل DEBUG فقط ، وفقط إذا كان التسجيل يوفر المعلومات التي لا تتوفر للمتصل. على وجه التحديد ، ليست هناك حاجة لتسجيل المواقف التي يتم فيها طرح استثناء (يجب أن يحتوي الاستثناء على جميع المعلومات ذات الصلة) ، أو حيث يتم تضمين المعلومات الوحيدة التي يتم تسجيلها في رمز خطأ. هذا مهم بشكل خاص في التفاعل بين إطار العمل والتطبيقات ، ولا يجب أن تؤدي الظروف التي تسببها تطبيقات الجهات الخارجية التي يتم التعامل معها بشكل صحيح بواسطة إطار العمل إلى تسجيل أعلى من مستوى DEBUG . المواقف الوحيدة التي يجب أن تؤدي إلى التسجيل على مستوى INFORMATIVE أو أعلى هي عندما تكتشف وحدة نمطية أو تطبيق خطأً في مستواه الخاص أو يأتي من مستوى أدنى.
  • عندما يُحتمل حدوث شرط يبرر عادةً بعض عمليات التسجيل عدة مرات ، فقد يكون من الجيد تنفيذ بعض آليات تحديد المعدل لمنع فائض السجلات بالعديد من النسخ المكررة لنفس المعلومات (أو مشابهة جدًا).
  • تعتبر حالات فقدان الاتصال بالشبكة أمرًا شائعًا ومن المتوقع تمامًا ، ولا يجب تسجيلها بدون مبرر. يجب تسجيل فقدان الاتصال بالشبكة الذي يكون له عواقب داخل التطبيق على مستوى DEBUG أو VERBOSE (اعتمادًا على ما إذا كانت العواقب خطيرة بدرجة كافية وغير متوقعة بما يكفي لتسجيل الدخول في إصدار الإصدار).
  • إن وجود نظام ملفات كامل على نظام ملفات يمكن الوصول إليه أو بالنيابة عن تطبيقات الجهات الخارجية لا يجب أن يتم تسجيله بمستوى أعلى من INFORMATIVE.
  • تعتبر البيانات غير الصالحة الواردة من أي مصدر غير موثوق به (بما في ذلك أي ملف موجود على وحدة تخزين مشتركة ، أو بيانات واردة عبر اتصال شبكة) متوقعة ويجب ألا تؤدي إلى أي تسجيل على مستوى أعلى من DEBUG عندما يتم اكتشاف أنه غير صالح (وحتى ذلك الحين يتم التسجيل) يجب أن تكون محدودة قدر الإمكان).
  • عند استخدامه على كائنات String ، ينشئ عامل + ضمنيًا مثيل StringBuilder بحجم المخزن المؤقت الافتراضي (16 حرفًا) ومن المحتمل أن تكون كائنات String مؤقتة أخرى. لذا فإن إنشاء كائنات StringBuilder بشكل صريح ليس أغلى من الاعتماد على عامل التشغيل + الافتراضي (ويمكن أن يكون أكثر كفاءة). ضع في اعتبارك أن الكود الذي يستدعي Log.v() يتم تجميعه وتنفيذه في إصدارات الإصدارات ، بما في ذلك بناء السلاسل ، حتى لو لم يتم قراءة السجلات.
  • يجب أن يكون أي تسجيل من المفترض أن يقرأه أشخاص آخرون وأن يكون متاحًا في إصدارات الإصدارات مقتضبًا دون أن يكون غامضًا ويجب أن يكون مفهومًا. هذا يشمل كل ما يصل إلى مستوى DEBUG .
  • عندما يكون ذلك ممكنًا ، استمر في تسجيل الدخول على سطر واحد. أطوال الأسطر التي تصل إلى 80 أو 100 حرف مقبولة. تجنب الأطوال التي تزيد عن 130 أو 160 حرفًا (بما في ذلك طول العلامة) إن أمكن.
  • إذا نجح تسجيل التقارير ، فلا تستخدمه أبدًا عند مستويات أعلى من VERBOSE .
  • إذا كنت تستخدم التسجيل المؤقت لتشخيص مشكلة يصعب إعادة إنتاجها ، فاحتفظ بها على مستوى DEBUG أو VERBOSE وقم بإرفاقها إذا كانت الكتل تسمح بتعطيلها في وقت الترجمة.
  • كن حذرا بشأن التسريبات الأمنية من خلال السجل. تجنب تسجيل المعلومات الخاصة. على وجه الخصوص ، تجنب تسجيل المعلومات حول المحتوى المحمي. هذا مهم بشكل خاص عند كتابة التعليمات البرمجية لإطار العمل لأنه ليس من السهل أن تعرف مسبقًا ما الذي سيكون معلومات خاصة أو محتوى محميًا ولن يكون كذلك.
  • لا تستخدم مطلقًا System.out.println() (أو printf() للكود الأصلي). تتم إعادة توجيه System.out و System.err إلى /dev/null ، لذلك لا يكون لتعليمات الطباعة أي تأثيرات مرئية. ومع ذلك ، لا يزال يتم تنفيذ كل بناء السلسلة الذي يحدث لهذه المكالمات.
  • القاعدة الذهبية للتسجيل هي أن سجلاتك قد لا تدفع السجلات الأخرى دون داعٍ إلى الخروج من المخزن المؤقت ، تمامًا كما قد لا يدفع الآخرون سجلاتك.

قواعد أسلوب جافتيست

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

testMethod_specificCase1 testMethod_specificCase2

void testIsDistinguishable_protanopia() {
    ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}