कोड शैली दिशानिर्देश

जावा भाषा नियम

हम मानक जावा कोड सम्मेलनों का पालन करते हैं। हमने उनसे कुछ नियम जोड़े:

1. अपवाद: बिना स्पष्टीकरण के कभी भी अवरोधन या अनदेखी न करें।
2. अपवाद: सामान्यीकृत अपवादों का उपयोग न करें, सिवाय पुस्तकालयों में कोड के, स्टैक के मूल में।
3. फाइनल: उन्हें उपयोग न करें।
4. आयात: पूरी तरह से आयात निर्दिष्ट करें।

जावा लाइब्रेरी नियम

एंड्रॉइड के लिए जावा पुस्तकालयों और उपकरणों के उपयोग के संबंध में समझौते हैं। कुछ मामलों में, कन्वेंशनों को बदला जा सकता है, उदाहरण के लिए, जैसे कि पुराने कोड का उपयोग करना जो अप्रयुक्त पैटर्न या लाइब्रेरी का उपयोग कर सकते हैं।

जावा शैली के नियम

जब सभी फ़ाइलों में एक सुसंगत शैली होती है, तो प्रोग्राम बनाए रखना बहुत आसान होता है। हम जावा प्रोग्रामिंग लैंग्वेज के लिए उनके कोड कन्वेंशनों में सन द्वारा परिभाषित मानक जावा प्रोग्रामिंग शैली का पालन करते हैं, कुछ अपवाद और परिवर्धन के साथ। यह शैली गाइड व्यापक और व्यापक है, और जावा समुदाय द्वारा भी व्यापक रूप से उपयोग किया जाता है।

इसके अलावा, हम कोड के लिए निम्नलिखित नियमों का उपयोग करने के लिए बाध्य हैं:

1. टिप्पणियाँ / Javadoc: उन्हें लिखें; एक मानक शैली का उपयोग करें।
2. छोटी विधियाँ: विशाल तरीके न लिखें।
3. फ़ील्ड्स: फ़ाइल के शीर्ष पर, या उनके उपयोग करने की विधि से ठीक पहले होनी चाहिए।
4. स्थानीय चर: दायरा सीमित करें।
5. आयात: Android; तृतीय-पक्ष (वर्णानुक्रम में); जावा (x)
6. इंडेंटेशन: 4 स्थान, बिना टैब के।
7. लाइन की लंबाई: 100 वर्ण।
8. फ़ील्ड नाम: गैर-सार्वजनिक और गैर-स्थिर फ़ील्ड "m" से शुरू होते हैं।
9. ब्रेसिज़: घुंघराले ब्रेसिज़ खोलना एक अलग लाइन पर नहीं है।
10. एनोटेशन: मानक एनोटेशन का उपयोग करें।
11. संकेताक्षर: शब्दों में शब्दों के रूप में संक्षिप्तीकरण का उपयोग करें, उदाहरण के लिए, XmlHttpRequest, getUrl (), आदि।
12. TODO शैली: "TODO: यहां एक विवरण लिखें।"
13. संगति: देखें कि आपके आसपास क्या है।

जावा भाषा नियम

अपवादों को नजरअंदाज न करें

आप ऐसे कोड लिखना चाह सकते हैं, जो अपवादों की उपेक्षा करते हैं, उदाहरण के लिए:

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."); } } 

  
  
• त्रुटि को पकड़ें और {} ब्लॉक में संबंधित मान को बदलें
  

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

  ध्यान दें कि प्रारंभिक अपवाद RuntimeException कंस्ट्रक्टर पर फेंका गया है। यदि आप जावा 1.3 संकलक का उपयोग कर रहे हैं, तो अपवाद को छोड़ दें।
  
• यदि आप सुनिश्चित हैं कि इस मामले में अपवाद की अनदेखी हो रही है, तो कम से कम टिप्पणी करें कि आपने ऐसा क्यों किया।
  

   /** 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! } 

आपको ऐसा नहीं करना चाहिए। लब्बोलुआब यह है कि एक अपवाद हो सकता है जिसकी आपको उम्मीद नहीं थी और परिणामस्वरूप, आवेदन स्तर पर त्रुटि पकड़ी जाएगी। यही है, अगर कोई नए प्रकार के अपवाद को जोड़ता है, तो संकलक आपको यह समझने में मदद नहीं कर पाएगा कि यह एक और त्रुटि है।

इस नियम के दुर्लभ अपवाद हैं: एक विशिष्ट परीक्षण कोड, या शीर्ष-स्तरीय कोड जहां आप सभी प्रकार की त्रुटियों को रोकना चाहते हैं (ताकि उपयोगकर्ता इंटरफ़ेस में प्रकट होने से रोकने के लिए, या किसी प्रकार के बैच कार्य को जारी रखने के लिए)।

सामान्य अपवादों के विकल्प:

• कैच ब्लॉक में अलग-अलग प्रत्येक अपवाद को एक ही प्रयास के बाद पकड़ें। यह सुविधाजनक नहीं हो सकता है, लेकिन यह अभी भी सभी अपवादों को पकड़ने का पसंदीदा तरीका है।
• एकाधिक प्रयास ब्लॉक के साथ अधिक बारीक त्रुटि से निपटने के लिए अपने कोड को संशोधित करें। पार्सिंग से अलग IO, प्रत्येक मामले में अलग से त्रुटियों को संभालें।
• अपवाद फेंक दो। कई मामलों में, आपको मौजूदा स्तर पर सभी अपवादों को संभालने की आवश्यकता नहीं है, बस विधि को फेंक दें।

याद रखें: अपवाद आपके दोस्त हैं! जब कंपाइलर इंगित करता है कि आप उन्हें नहीं पकड़ रहे हैं तो क्रोधित न हों।

finalizers

यह क्या है : कचरा संग्रहकर्ता द्वारा किसी वस्तु को एकत्र करने से पहले अंतिम रूप प्रोग्राम कोड चलाने का एक तरीका है।
पेशेवरों : सफाई, विशेष रूप से बाहरी संसाधनों में उपयोगी हो सकता है।
विपक्ष : कोई गारंटी नहीं है कि फाइनल को कब बुलाया जाएगा, और सामान्य तौर पर, क्या इसे बुलाया जाएगा।

समाधान : हम फाइनल का उपयोग नहीं करते हैं। ज्यादातर मामलों में, आपको अंतिम रूप से जो कुछ भी चाहिए, आप अपवाद हैंडलिंग के साथ कर सकते हैं। यदि आपको वास्तव में एक अंतिम रूप देने की आवश्यकता है, तो पास () विधि और दस्तावेज़ की घोषणा करें जब इसे बिल्कुल कहा जाएगा।

आयात

आयात में वाइल्डकार्ड

यह क्या है : जब आप फू पैकेज से बार क्लास का उपयोग करना चाहते हैं, तो ऐसा करने के दो तरीके हैं:

1.  import foo.*; 

2.  import foo.Bar; 

प्रो # 1 : संभावित आयात बयानों की संख्या को संभावित रूप से कम कर देता है।
प्रो # 2 : यह स्पष्ट करता है कि वास्तव में किस वर्ग का उपयोग किया जाता है। उन लोगों के लिए कोड को अधिक पठनीय बनाता है जो इसका समर्थन करते हैं।

समाधान : किसी भी Android कोड को आयात करने के लिए शैली # 2 का उपयोग करें। मानक पुस्तकालयों (java.util। *, Java.io. *, आदि) और इकाई परीक्षण कोड (junit.framework। *) के लिए एक स्पष्ट अपवाद बनाया गया है।

टिप्पणियाँ / Javadoc

प्रत्येक फ़ाइल में बहुत शुरुआत में कॉपीराइट नोटिस होना चाहिए। अगले पैकेज और आयात विवरण की घोषणाएं हैं, प्रत्येक ब्लॉक को एक खाली स्ट्रिंग द्वारा अलग किया गया है। उनके बाद कक्षा या इंटरफ़ेस घोषणाएँ होती हैं। बताइए कि जावदोक टिप्पणियों में वर्ग क्या करता है।

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

प्रत्येक वर्ग और गैर-तुच्छ सार्वजनिक पद्धति में एक जावदोक होना चाहिए जिसमें कम से कम एक वाक्यांश हो, जिसमें यह वर्णित हो कि क्या होता है। वाक्यांश को एक 3 व्यक्ति वर्णनात्मक क्रिया के साथ शुरू करना चाहिए। उदाहरण:

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

तुच्छ पाने के लिए और सेटफू () जैसे तरीकों के लिए आपको जावदॉक का वर्णन करने की आवश्यकता नहीं है यदि आपका जावेदोक केवल "फू फू सेट" कहता है। यदि विधि कुछ अधिक जटिल करती है (उदाहरण के लिए, कुछ प्रतिबंधों का अवलोकन करना, या यदि इसके कार्यों का स्वयं के बाहर एक महत्वपूर्ण प्रभाव है), तो इसे प्रलेखित किया जाना चाहिए। और अगर यह सिर्फ फू का मतलब नहीं है, तो आपको इसका दस्तावेज भी बनाना चाहिए।

सामान्य तौर पर, आपने जो भी विधि लिखी है, उसमें जावदोक से लाभ है, चाहे वह सार्वजनिक हो या न हो। सार्वजनिक विधियाँ एपीआई का हिस्सा हैं, और इसलिए उन्हें जावदोक में एक विवरण की आवश्यकता होती है।

Javadocs लिखने के लिए, आपको Sun 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. तृतीय-पक्ष आयात (कॉम, जूनिट, नेट, ऑर्ग)।
3. java और javax।

आईडीई सेटिंग्स का पूरी तरह से पालन करने के लिए, आयात इस तरह दिखना चाहिए:

• प्रत्येक समूह के भीतर वर्णानुक्रम में क्रमबद्ध।
• अपरकेस अक्षर लोअरकेस अक्षर (उदाहरण के लिए, जेड के सामने) के सामने होना चाहिए।
• मुख्य समूहों को एक खाली लाइन द्वारा अलग किया जाना चाहिए।

क्यों?
आदेश ऐसा है:

• जो आयात लोग पहले देखना चाहते हैं, वे सबसे ऊपर हैं (Android)।
• जो आयात लोग अंतिम बार देखना चाहते हैं, वह नीचे (जावा) है।
• लोग आसानी से इस शैली का उपयोग कर सकते हैं।
• आईडीई इस शैली का पालन कर सकता है।

इंडेंट

हम ब्लॉक के लिए 4 रिक्त स्थान का उपयोग करते हैं। हम कभी भी टैब का उपयोग नहीं करते हैं। हम लाइन ब्रेक के लिए 8 स्थानों का उपयोग करते हैं, जिसमें फ़ंक्शन कॉल और असाइनमेंट शामिल हैं, उदाहरण के लिए इस तरह से सही तरीके से:

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

और इतना गलत:

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

क्षेत्र के नाम

• गैर-स्थिर और गैर-सार्वजनिक नाम "एम" से शुरू होते हैं।
• स्थिर क्षेत्र "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(); // ok } if (condition) body(); // ok 

लेकिन यह असंभव है:

 if (condition) body(); // bad 

लाइन की लंबाई

कोड में पाठ की प्रत्येक पंक्ति 100 वर्णों से अधिक नहीं होनी चाहिए।
अपवाद: यदि टिप्पणी में उदाहरण कमांड, या एक URL है (यह कॉपी / पेस्ट का उपयोग करने के लिए अधिक सुविधाजनक है)।
अपवाद: आयात के तार 100 वर्णों से अधिक लंबे हो सकते हैं, क्योंकि लोग शायद ही कभी उन्हें देखते हैं। यह लेखन टूल को भी आसान बनाता है।

नामों में संक्षिप्तता

शब्दों के रूप में संक्षिप्त और संक्षिप्त रूप में सोचें। नाम अधिक पठनीय हैं:

अच्छी तरह से	बीमार
XmlHttpRequest	XMLHttpRequest
getCustomerId	getCustomerID

यह शैली तब भी लागू होती है जब संक्षिप्त नाम और संक्षिप्त नाम पूरा नाम होता है:

अच्छी तरह से	बीमार
कक्षा html	कक्षा HTML
स्ट्रिंग url;	स्ट्रिंग URL
लंबी आईडी;	लंबी आईडी;

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. 

यदि आपकी टिप्पणी "भविष्य में कुछ करें," तो सुनिश्चित करें कि इसमें एक विशिष्ट तिथि (1 जनवरी, 2011), या एक विशिष्ट "संस्करण 2.1 के बाद हटाएं" घटना शामिल है।

संगति

यदि आप कोड बदलते हैं, तो अपने आसपास के कोड को देखने और उसकी शैली निर्धारित करने के लिए एक मिनट का समय लें। यदि इसमें रिक्त स्थान का उपयोग किया जाता है, तो आपको उनका उपयोग करना चाहिए। यदि टिप्पणियों में तारों का एक छोटा सा सेट होता है, तो आपको उनका उपयोग करना चाहिए।

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