योगदान देने वालों के लिए AOSP Java कोड स्टाइल

इस पेज पर दी गई कोड शैलियां Android ओपन सोर्स प्रोजेक्ट (AOSP). Android प्लैटफ़ॉर्म में योगदान जो इन नियमों का पालन नहीं करते हैं, आमतौर पर स्वीकार नहीं किए जाते. बुध ध्यान दें कि सभी मौजूदा कोड इन नियमों का पालन नहीं करते, लेकिन हम सभी नीति का पालन करना होगा. कोडिंग का सम्मान करें बिना किसी भेदभाव के सभी को ध्यान में रखकर, इस्तेमाल किए जाने वाले शब्दावली के उदाहरणों के लिए.

नियमित तौर पर वीडियो अपलोड करना

सबसे आसान नियमों में से एक है 'एक जैसा रखें'. अगर आपको कोड में बदलाव करना है, तो मिनटों में, आस-पास के कोड को देखें और उसकी स्टाइल तय करें. अगर ऐसा है, तो कोड if क्लॉज़ के आस-पास स्पेस का इस्तेमाल करता है, आपको भी ऐसा करना चाहिए. अगर कोड टिप्पणियों के आसपास सितारों के छोटे बॉक्स होते हैं, तो अपनी टिप्पणियों में साथ ही, उनके चारों ओर तारों के छोटे-छोटे बॉक्स भी दिख सकते हैं.

स्टाइल के लिए दिशा-निर्देश होने का मतलब है कि एक सामान्य शब्दावली का इस्तेमाल किया जाना चाहिए इससे पाठक आपकी बात पर ध्यान दे पाते हैं. बात करने के लिए अलग-अलग तरीके हैं. हम यहां ग्लोबल स्टाइल से जुड़े नियम पेश करते हैं, ताकि आप जान सकें शब्दावली, लेकिन स्थानीय शैली भी महत्वपूर्ण है. अगर हर बार अलग-अलग कोड के साथ फ़ाइल काफ़ी अलग दिखती है और मौजूदा कोड से काफ़ी अलग दिखती है, जब वे इसे पढ़ते हैं, तो पाठकों को उनका तालमेल बिगड़ जाता है. इसे आज़माएँ इससे बचें.

Java के लिए भाषा के नियम

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) {
    ...
}
  • गड़बड़ी को बेहतर तरीके से मैनेज करने के लिए, अपने कोड को रीफ़ैक्टर करें, एक से ज़्यादा ब्लॉक आज़माएं. IO को पार्स करने से अलग करें और गड़बड़ियों को हैंडल करें करते हैं.
  • अपवाद को फिर से लागू करें. कई बार आपको अपवाद के बिना नहीं कर सकते, तो बस विधि को उसे फेंकने दें.

याद रखें कि अपवाद आपके दोस्त हैं! जब कंपाइलर शिकायत करता है कि आप कोई अपवाद नहीं मिलता, तो घबराएं नहीं. मुस्कुराएं! कंपाइलर ने इसे बनाया इससे आपको अपने कोड में रनटाइम की समस्याओं को पहचानने में आसानी होती है.

फ़ाइनलाइज़र का इस्तेमाल न करें

फ़ाइनलाइज़र, कोड का एक हिस्सा एक्ज़ीक्यूट करने का तरीका हैं, जब कोई ऑब्जेक्ट इकट्ठा किया जाता है. हालांकि, क्लीनअप के लिए फ़ाइनलाइज़र काम आ सकते हैं (खास तौर पर बाहरी संसाधनों के मामले में), इसकी कोई गारंटी नहीं है कि फ़ाइनलाइज़र को कॉल किया जाएगा या यह कि किसी भी तरह से कॉल किया जाएगा.

Android, फ़ाइनलाइज़र का इस्तेमाल नहीं करता. ज़्यादातर मामलों में, आपको के बजाय, उन्हें अच्छी तरह से अपवाद मैनेज किया जा सकता है. अगर आपको फ़ाइनलाइज़र चाहिए, तो close() मेथड (या इससे मिलता-जुलता) और दस्तावेज़ को तब तय करें, जब तरीके को कॉल करने की ज़रूरत है (देखें उदाहरण के लिए, इनपुटStream). इस मामले में, हालांकि, ऐसा करना ज़रूरी नहीं है. फ़ाइनलाइज़र का इस्तेमाल भी किया जा सकता है, बशर्ते इससे लॉग भरने की संभावना न हो.

पूरी तरह क्वालिफ़ाइड इंपोर्ट

जब आपको foo पैकेज से Bar क्लास का इस्तेमाल करना हो, तो आपके पास दो इसे इंपोर्ट करने के संभावित तरीके:

  • import foo.*;

    इंपोर्ट स्टेटमेंट की संख्या को कम कर सकता है.

  • import foo.Bar;

    इससे साफ़ तौर पर पता चलता है कि किन क्लास का इस्तेमाल किया जा रहा है और कोड ज़्यादा है रखरखाव करने वाले लोग आसानी से पढ़ सकते हैं.

सभी Android कोड इंपोर्ट करने के लिए import foo.Bar; का इस्तेमाल करें. अगर आप Java स्टैंडर्ड लाइब्रेरी (java.util.*, java.io.*, वगैरह) और यूनिट टेस्ट कोड (junit.framework.*).

Java लाइब्रेरी के नियम

Android की Java लाइब्रेरी और टूल इस्तेमाल करने के तरीके भी हैं. तय सीमा में कुछ मामलों में, कन्वेंशन अहम तरीकों और पुराने कोड में बदल गया है किसी ऐसे पैटर्न या लाइब्रेरी का इस्तेमाल कर सकता है जो अब काम नहीं करता. ऐसे कोड का इस्तेमाल करते समय, मौजूदा स्टाइल को जारी रखने में कोई समस्या नहीं है. नए कॉम्पोनेंट बनाते समय हालांकि, उन लाइब्रेरी का इस्तेमाल कभी न करें जो अब काम नहीं करतीं.

Java की स्टाइल के नियम

Javadoc स्टैंडर्ड टिप्पणियों का इस्तेमाल करें

हर फ़ाइल के सबसे ऊपर कॉपीराइट स्टेटमेंट होना चाहिए. इसके बाद, पैकेज और इंपोर्ट स्टेटमेंट (हर ब्लॉक को एक खाली लाइन से अलग किया जाता है) और आख़िर में क्लास या इंटरफ़ेस की जानकारी होगी. Javaडॉक की टिप्पणियों में, बताता है कि क्लास या इंटरफ़ेस क्या करता है. 

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

आपको आसान पाने और सेट करने के लिए Java फ़ाइलें लिखने की ज़रूरत नहीं है setFoo() अगर आपके सभी Javadoc में कहा जाएगा कि "sets Foo" है. अगर आपने तरीका कुछ ज़्यादा जटिल काम करता है (जैसे, कंस्ट्रेंट लागू करना) या इसका कोई गंभीर दुष्प्रभाव भी है), तो आपको इसे दस्तावेज़ में दर्ज करना होगा. अगर ऐसा नहीं है "Foo" प्रॉपर्टी क्या है का मतलब है, आपको इसे डॉक्यूमेंट करना चाहिए.

आपके लिखें जाने पर, सार्वजनिक रूप से या किसी और तरीके से, Javadoc से आपको फ़ायदा होगा. सार्वजनिक तरीके API का हिस्सा होते हैं, इसलिए Javadoc की ज़रूरत होती है. Android पर Java फ़ाइलें लिखने के लिए कोई खास स्टाइल लागू नहीं करता है टिप्पणियां: हालांकि, आपको Javadoc टूल के लिए दस्तावेज़ में टिप्पणियां लिखने का तरीका लेख में दिए गए निर्देशों का पालन करना होगा.

छोटी विधियां लिखें

जब मुमकिन हो, तब तरीकों को छोटा रखें और किसी विषय पर फ़ोकस करें. हम मानते हैं कि लंबे समय तक तरीके कभी-कभी सही होते हैं. इसलिए, लंबाई. अगर कोई तरीका 40 से ज़्यादा लाइनों में दिख रहा है, तो देखें कि क्या उन्हें प्रोग्राम की बनावट को नुकसान पहुंचाए बिना अलग किया जाना चाहिए.

स्टैंडर्ड जगहों में फ़ील्ड तय करना

फ़ाइल के शीर्ष पर या फ़ाइल के ठीक पहले इस्तेमाल करती हैं.

वैरिएबल के स्कोप को सीमित करें

लोकल वैरिएबल का स्कोप कम से कम रखें. यह आपके कोड को पढ़ना आसान बनाता है और रखरखाव करता है. साथ ही, गड़बड़ी की संभावना नहीं है. हर वैरिएबल को सबसे पहले ब्लॉक शामिल है, जिसमें वैरिएबल के सभी इस्तेमाल शामिल होते हैं.

उस पॉइंट पर लोकल वैरिएबल का एलान करें जहां उन्हें पहली बार इस्तेमाल किया गया है. करीब-करीब हर लोकल वैरिएबल के एलान में एक इनीशियलाइज़र होना चाहिए. अगर आपके पास वैरिएबल शुरू करने के लिए, अब तक ज़रूरी जानकारी नहीं है तब तक एलान को टाल दें.

'कैच करें' स्टेटमेंट इन अपवाद के दायरे में आते हैं. अगर कोई वैरिएबल इससे शुरू किया जाता है, तो किसी ऐसे तरीके की रिटर्न वैल्यू जो जांचे गए अपवाद की तरह दिखता है, तो यह ट्राई ब्लॉक में शुरू किया गया. अगर वैल्यू का इस्तेमाल ब्लॉक का इस्तेमाल करें, तो इसे ट्राइ ब्लॉक से पहले एलान किया जाना चाहिए, जहां यह इसे अभी समझदारी से शुरू नहीं किया जा सकता: 

// 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));

हालांकि, इस मामले से बचने के लिए, 'ट्राई-कैच' सुविधा को इनकैप्सुलेट करना भी आसान हो सकता है ब्लॉक करें: 

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 (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 सेटिंग से पूरी तरह मैच करने के लिए, इंपोर्ट इस तरह का होना चाहिए:

  • हर ग्रुप में वर्णमाला के क्रम से लगाएं और लोअर टाइम से पहले कैपिटल लेटर का इस्तेमाल करें अंग्रेज़ी के छोटे अक्षर (उदाहरण के लिए, a से पहले Z)
  • हर बड़े ग्रुप को एक खाली लाइन से अलग किया गया हो (android, com, junit, net, org, java, javax)

पहले, ऑर्डर करने के लिए किसी स्टाइल की ज़रूरत नहीं थी, मतलब IDEs या तो ऑर्डर को हमेशा बदल रहे थे या IDE डेवलपर को यह विकल्प, ऑटोमैटिक इंपोर्ट मैनेजमेंट की सुविधाओं को बंद करता है और उन्हें मैन्युअल तरीके से मैनेज करता है को समझ लिया. इसे खराब माना गया था. जब Java-स्टाइल के बारे में पूछा गया, तो अलग-अलग स्टाइल में बहुत कुछ पसंद आया और यह Android पर आ गया बस "कोई क्रम चुनें और नियमित रूप से काम करें." इसलिए, हमने एक स्टाइल चुना, स्टाइल गाइड को अपडेट किया और 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 वर्ण हो सकते हैं. अपवाद:

  • अगर टिप्पणी की लाइन में उदाहरण के तौर पर कोई निर्देश दिया गया है या लिटरल यूआरएल मौजूद है 100 वर्णों से ज़्यादा, तो वह पंक्ति आसानी से काटने और चिपकाने में मदद करता है.
  • इंपोर्ट की गई लाइनें इस सीमा से ज़्यादा हो सकती हैं, क्योंकि ऐसा बहुत कम होता है कि लोग इन्हें देख पाएं (इससे टूल को लिखना भी आसान हो जाता है).

मानक Java एनोटेशन का उपयोग करें

समान भाषा के लिए एनोटेशन से पहले, दूसरे मॉडिफ़ायर से पहले ऐसा होना चाहिए एलिमेंट. सामान्य मार्कर एनोटेशन (उदाहरण के लिए, @Override) को भाषा एलिमेंट के साथ एक ही लाइन. अगर एक से ज़्यादा एनोटेशन हैं, या पैरामीटर वाले एनोटेशन, उन्हें एक-एक लाइन में वर्णमाला के क्रम में.

Java में पहले से तय किए गए तीन एनोटेशन के लिए, Android के स्टैंडर्ड तरीके हैं:

  • @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अनुरोध एक्सएमएलHTTPअनुरोध
ग्राहक आईडी पाएं 'ग्राहक आईडी'
क्लास html क्लास एचटीएमएल
स्ट्रिंग यूआरएल स्ट्रिंग यूआरएल
लंबा आईडी लंबा आईडी

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 लेवल (यह इस बात पर निर्भर करता है कि नतीजे काफ़ी गंभीर हो सकते हैं और किसी रिलीज़ में लॉग इन करने की उम्मीद नहीं की जा सकती बिल्ड).
  • फ़ाइल सिस्टम में पूरा फ़ाइल सिस्टम होना चाहिए, जिसे ऐक्सेस किया जा सके या जिस पर तीसरे पक्ष के ऐप्लिकेशन की ओर से किसी लेवल पर लॉग नहीं किया जाना चाहिए से ज़्यादा है.
  • किसी भी गैर-भरोसेमंद सोर्स से अमान्य डेटा आ रहा है (इसमें वे फ़ाइलें भी शामिल हैं जो शेयर किया गया स्टोरेज या नेटवर्क से मिलने वाला डेटा कनेक्शन) अपेक्षित माना जाता है और 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 पर रीडायरेक्ट किया गया, इसलिए आपके प्रिंट स्टेटमेंट में कोई दिखने वाले इफ़ेक्ट. हालांकि, तब भी ये कॉल एक्ज़ीक्यूट होते रहते हैं.
  • लॉग इन करने का सबसे अच्छा नियम यह है कि आपका लॉग गैर-ज़रूरी अन्य लॉग को बफ़र से बाहर निकालें, जैसे कि दूसरे लॉग आपको परेशान नहीं करना है.

Javaटेस्ट स्टाइल के नियम

परीक्षण विधि का नाम रखने के तरीके अपनाएं और अंडरस्कोर का इस्तेमाल करके उन्हें अलग करें दिए गए केस में से किसका टेस्ट किया जा रहा है. यह स्टाइल आपको इससे यह समझने में आसानी होती है कि कौनसे केस की जांच की जा रही है. उदाहरण के लिए: 

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