سبک کد جاوا AOSP برای مشارکت کنندگان

سبک های کد موجود در این صفحه قوانین سختگیرانه ای برای مشارکت کد جاوا در پروژه متن باز اندروید (AOSP) هستند. مشارکت در پلتفرم Android که از این قوانین پیروی نمی کند معمولاً پذیرفته نمی شود . می‌دانیم که همه کدهای موجود از این قوانین پیروی نمی‌کنند، اما انتظار داریم همه کدهای جدید مطابقت داشته باشند. برای اکوسیستم فراگیرتر، به کدنویسی با احترام به مثال‌هایی از اصطلاحات برای استفاده و اجتناب از آن مراجعه کنید.

سازگار باشید

یکی از ساده ترین قوانین، سازگاری است. اگر در حال ویرایش کد هستید، چند دقیقه به کد اطراف نگاه کنید و سبک آن را تعیین کنید. اگر در آن کد از فضاهای خالی در اطراف بندهای if استفاده کنید، شما نیز باید این کار را انجام دهید. اگر نظرات کد جعبه‌های کوچکی از ستاره‌ها در اطراف خود دارند، کاری کنید که نظرات شما نیز جعبه‌های کوچکی از ستاره‌ها در اطراف خود داشته باشند.

هدف از داشتن دستورالعمل‌های سبک، داشتن واژگان مشترک کدنویسی است، بنابراین خوانندگان می‌توانند به جای اینکه چگونه آن را بیان می‌کنید، روی آنچه می‌گویید تمرکز کنند. ما قوانین سبک جهانی را در اینجا ارائه می دهیم تا واژگان را بدانید، اما سبک محلی نیز مهم است. اگر کدی که به یک فایل اضافه می کنید به شدت با کد موجود در اطراف آن متفاوت به نظر می رسد، خوانندگان را هنگام خواندن آن از ریتم خارج می کند. سعی کنید از این کار اجتناب کنید.

قوانین زبان جاوا

Android از قوانین کدنویسی استاندارد جاوا با قوانین اضافی که در زیر توضیح داده شده است پیروی می کند.

استثناها را نادیده نگیرید

نوشتن کدی که استثنایی را نادیده می گیرد، می تواند وسوسه انگیز باشد، مانند:

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

این کار را نکن در حالی که ممکن است فکر کنید کد شما هرگز با این شرایط خطا مواجه نخواهد شد یا رسیدگی به آن مهم نیست، نادیده گرفتن این نوع استثناء باعث ایجاد مین هایی در کد شما می شود تا شخص دیگری روزی آن را فعال کند. شما باید هر استثنا در کد خود را به روشی اصولی مدیریت کنید. حمل و نقل خاص بسته به مورد متفاوت است.

" هر وقت کسی یک بند خالی داشته باشد باید احساس ترسناکی داشته باشد. قطعاً مواقعی وجود دارد که واقعاً کار درستی است، اما حداقل باید به آن فکر کنید. در جاوا نمی توانید از احساس وحشتناک فرار کنید. " - جیمز گاسلینگ

گزینه های قابل قبول (به ترتیب اولویت) عبارتند از:

  • استثنا را به تماس گیرنده روش خود بیاندازید. 
      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) {
    ...
}
  • کد خود را مجدداً اصلاح کنید تا با چندین بلوک آزمایشی، خطاهای دقیق تری را مدیریت کنید. IO را از تجزیه جدا کنید و خطاها را در هر مورد جداگانه مدیریت کنید.
  • استثنا را دوباره برگردانید. در بسیاری از مواقع نیازی به گرفتن استثنا در این سطح ندارید، فقط اجازه دهید روش آن را پرتاب کند.

به یاد داشته باشید که استثناها دوست شما هستند! وقتی کامپایلر شکایت می‌کند که شما استثنا نمی‌گیرید، اخم نکنید. لبخند بزن! کامپایلر به راحتی می‌تواند مشکلات زمان اجرا را در کدتان تشخیص دهد.

از نهایی کننده ها استفاده نکنید

Finalizers راهی برای اجرای یک تکه کد در هنگام جمع‌آوری یک شیء زباله است. در حالی که نهایی کننده ها می توانند برای پاکسازی مفید باشند (به ویژه منابع خارجی)، هیچ تضمینی در مورد زمان فراخوانی نهایی کننده (یا حتی فراخوانی آن) وجود ندارد.

اندروید از نهایی کننده ها استفاده نمی کند. در بیشتر موارد، می توانید به جای آن از مدیریت استثنایی خوب استفاده کنید. اگر کاملاً به یک نهایی کننده نیاز دارید، یک متد close() (یا مشابه) تعریف کنید و دقیقاً زمانی که آن متد باید فراخوانی شود مستند کنید (برای مثال به InputStream مراجعه کنید). در این مورد، چاپ یک پیام گزارش کوتاه از نهایی کننده مناسب است، اما لازم نیست، تا زمانی که انتظار نمی رود که سیاهه ها را پر کند.

واردات کاملا واجد شرایط

هنگامی که می خواهید از class Bar از بسته foo استفاده کنید، دو راه ممکن برای وارد کردن آن وجود دارد:

  • import foo.*;

    به طور بالقوه تعداد اظهارنامه های واردات را کاهش می دهد.

  • import foo.Bar;

    مشخص می کند که چه کلاس هایی استفاده می شوند و کد برای نگهدارنده ها خواناتر است.

از import foo.Bar; برای وارد کردن تمام کدهای اندروید یک استثنا صریح برای کتابخانه های استاندارد جاوا ( java.util.* ، java.io.* ، و غیره) و کد آزمون واحد ( junit.framework.* ) ایجاد شده است.

قوانین کتابخانه جاوا

قراردادهایی برای استفاده از کتابخانه ها و ابزارهای جاوا اندروید وجود دارد. در برخی موارد، این قرارداد به روش‌های مهمی تغییر کرده است و کدهای قدیمی‌تر ممکن است از یک الگو یا کتابخانه منسوخ استفاده کنند. هنگام کار با چنین کدی، ادامه دادن سبک موجود اشکالی ندارد. با این حال، هنگام ایجاد اجزای جدید، هرگز از کتابخانه های منسوخ استفاده نکنید.

قوانین سبک جاوا

از نظرات استاندارد Javadoc استفاده کنید

هر فایل باید یک عبارت کپی رایت در بالا داشته باشد، به دنبال آن عبارات بسته و واردات (هر بلوک با یک خط خالی جدا شده است)، و در نهایت اعلان کلاس یا رابط. در نظرات Javadoc، آنچه را که کلاس یا رابط انجام می دهد، شرح دهید.

/*
 * Copyright yyyy 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 {
    ...
}

هر کلاس و متد عمومی غیر پیش پا افتاده ای که می نویسید باید حاوی یک نظر Javadoc با حداقل یک جمله باشد که توضیح دهد کلاس یا متد چه می کند. این جمله باید با فعل توصیفی سوم شخص شروع شود.

نمونه ها 

/** 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) {
    ...
}

اگر تمام جاوادوک شما می گوید "sets Foo" است، نیازی به نوشتن Javadoc برای متدهای بی اهمیت دریافت و تنظیم مانند setFoo() ندارید. اگر روش کار پیچیده‌تری انجام می‌دهد (مانند اعمال یک محدودیت یا یک عارضه جانبی مهم)، پس باید آن را مستند کنید. اگر مشخص نیست که ویژگی "فو" به چه معناست، باید آن را مستند کنید.

هر روشی که بنویسید، چه عمومی و چه در غیر این صورت، از Javadoc سود می برد. متدهای عمومی بخشی از یک API هستند و بنابراین به Javadoc نیاز دارند. Android سبک خاصی را برای نوشتن نظرات Javadoc اعمال نمی کند، اما باید دستورالعمل های نحوه نوشتن نظرات سند برای ابزار 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. واردات اندروید
  2. واردات از اشخاص ثالث ( com , junit , net , org )
  3. java و javax

برای مطابقت دقیق با تنظیمات IDE، واردات باید به صورت زیر باشد:

  • حروف الفبا در هر گروه، با حروف بزرگ قبل از حروف کوچک (به عنوان مثال، Z قبل از a)
  • با یک خط خالی بین هر گروه اصلی ( android ، com ، junit ، net ، org ، java ، javax ) جدا شده است.

در اصل، نیازی به سبک در سفارش وجود نداشت، به این معنی که IDE ها یا همیشه سفارش را تغییر می دادند یا توسعه دهندگان IDE باید ویژگی های مدیریت واردات خودکار را غیرفعال می کردند و به صورت دستی واردات را حفظ می کردند. این بد تلقی شد. هنگامی که از سبک جاوا پرسیده شد، سبک‌های ترجیحی بسیار متفاوت بودند و به آن رسید که اندروید به سادگی «انتخاب یک سفارش و سازگاری» داشت. بنابراین ما یک سبک را انتخاب کردیم، راهنمای سبک را به روز کردیم و IDE ها را وادار به اطاعت از آن کردیم. انتظار داریم همانطور که کاربران IDE روی کد کار می کنند، واردات در همه بسته ها بدون تلاش مهندسی اضافی با این الگو مطابقت داشته باشد.

ما این سبک را طوری انتخاب کردیم که:

  • وارداتی که مردم در ابتدا می‌خواهند به آن نگاه کنند، در بالاترین سطح قرار دارند ( android ).
  • وارداتی که مردم می خواهند به آن نگاه کنند حداقل در پایین ترین سطح ( java ) قرار دارند.
  • انسان ها به راحتی می توانند از سبک پیروی کنند.
  • IDE ها می توانند از سبک پیروی کنند.

واردات استاتیک را بالاتر از همه واردات سفارش داده شده به همان روش واردات معمولی قرار دهید.

از فضاها برای تورفتگی استفاده کنید

ما از چهار (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 کاراکتر باشد.
  • خطوط واردات می توانند از حد مجاز عبور کنند زیرا انسان به ندرت آنها را می بیند (این کار نوشتن ابزار را نیز ساده می کند).

از حاشیه نویسی های استاندارد جاوا استفاده کنید

حاشیه نویسی باید قبل از سایر اصلاح کننده ها برای عنصر زبان مشابه باشد. حاشیه نویسی نشانگر ساده (به عنوان مثال، @Override ) را می توان در همان خط با عنصر زبان فهرست کرد. اگر چندین حاشیه نویسی یا حاشیه نویسی پارامتری وجود دارد، آنها را به ترتیب حروف الفبا در یک خط فهرست کنید.

روش های استاندارد اندروید برای سه حاشیه نویسی از پیش تعریف شده در جاوا عبارتند از:

  • هر زمان که استفاده از عنصر حاشیه نویسی ممنوع شد، از حاشیه نویسی @Deprecated استفاده کنید. اگر از حاشیه‌نویسی @Deprecated استفاده می‌کنید، باید یک برچسب Javadoc @deprecated نیز داشته باشید و باید یک پیاده‌سازی جایگزین نام‌گذاری کند. علاوه بر این، به یاد داشته باشید که یک روش @Deprecated همچنان باید کار کند . اگر کد قدیمی را می‌بینید که دارای برچسب جاوادوک @deprecated است، حاشیه‌نویسی @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 مورد نیاز است، کد را تغییر دهید تا عناصر نرم افزار در جایی که حاشیه نویسی اعمال می شود جدا شود.

کلمات اختصاری را به عنوان کلمات در نظر بگیرید

در نامگذاری متغیرها، متدها و کلاسها، کلمات اختصاری و اختصاری را به عنوان کلماتی در نظر بگیرید تا نامها خواناتر شوند:

خوب بد
XmlHttpRequest XMLHTTPrequest
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 هدایت می شوند، بنابراین عبارات چاپی شما هیچ اثر قابل مشاهده ای ندارند. با این حال، تمام ساختارهای رشته‌ای که برای این تماس‌ها اتفاق می‌افتد همچنان اجرا می‌شوند.
  • قانون طلایی ورود به سیستم این است که لاگ های شما ممکن است بی جهت دیگر لاگ ها را از بافر خارج نکنند، همانطور که دیگران ممکن است لاگ های شما را خارج نکنند.

قوانین سبک Javatests

از قراردادهای نامگذاری روش آزمایش پیروی کنید و از یک خط زیر برای جدا کردن موارد مورد آزمایش از مورد خاص در حال آزمایش استفاده کنید. این سبک دیدن مواردی که در حال آزمایش هستند را آسان تر می کند. به عنوان مثال: 

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))
}