स्टाइल गाइड बनाएं

किसी समस्या की शिकायत करें सोर्स देखें रात · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

BUILD फ़ाइल फ़ॉर्मैट, Go के तरीके जैसा ही है, जहां एक स्टैंडर्ड फ़ॉर्मैट इस्तेमाल किया जाता है टूल से फ़ॉर्मैटिंग से जुड़ी ज़्यादातर समस्याएं हल हो जाती हैं. Buildier एक ऐसा टूल है जो एक स्टैंडर्ड स्टाइल में सोर्स कोड को छोड़ता है. इसलिए, हर BUILD फ़ाइल को उसी ऑटोमेटेड तरीके से फ़ॉर्मैट किया जाता है, जिससे फ़ॉर्मैट करने के दौरान कोई समस्या नहीं आती कोड समीक्षाएं. इससे टूल को समझने, बदलाव करने, और BUILD फ़ाइलें जनरेट करें.

BUILD की फ़ाइल फ़ॉर्मैटिंग, buildifier के आउटपुट से मेल खानी चाहिए.

फ़ॉर्मैट करने का उदाहरण

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

फ़ाइल का स्ट्रक्चर

सुझाव: नीचे दिए गए क्रम का इस्तेमाल करें (हर एलिमेंट ज़रूरी नहीं है):

  • पैकेज का ब्यौरा (एक टिप्पणी)

  • सभी load() स्टेटमेंट

  • package() फ़ंक्शन.

  • नियमों और मैक्रो को कॉल करने की सुविधा

बिल्डिफ़ायर स्टैंडअलोन टिप्पणी और टिप्पणी के बीच फ़र्क़ करता है किसी एलिमेंट के साथ अटैच किया जाता है. अगर कोई टिप्पणी किसी खास एलिमेंट के साथ अटैच नहीं है, तो इसके बाद की खाली लाइन. ऑटोमेटेड सिस्टम (कार्रवाइयों को अपने-आप पूरा करने वाला सिस्टम) बनाते समय, अंतर अहम है बदलाव (उदाहरण के लिए, किसी नियम को मिटाते समय किसी टिप्पणी को बनाए रखना या हटाना).

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

मौजूदा पैकेज में टारगेट के रेफ़रंस

फ़ाइलों को पैकेज डायरेक्ट्री के पाथ से रेफ़र किया जाना चाहिए (.. जैसे किसी अप-रेफ़रंस का इस्तेमाल किए बिना). जनरेट की गई फ़ाइलें इससे पहले ":" लगा होता है ताकि यह बताया जा सके कि ये सोर्स नहीं हैं. सोर्स फ़ाइलें : से पहले नहीं जोड़ा जाना चाहिए. नियमों की शुरुआत में : होना चाहिए. इसके लिए उदाहरण के लिए, मान लीजिए कि x.cc एक सोर्स फ़ाइल है:

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

टारगेट का नाम

टारगेट के नामों में पूरी जानकारी होनी चाहिए. अगर किसी टारगेट में एक सोर्स फ़ाइल है, तो टारगेट के लिए आम तौर पर उस सोर्स से लिया गया नाम होना चाहिए (उदाहरण के लिए, chat.cc के लिए cc_library का नाम chat या java_library हो सकता है DirectMessage.java का नाम direct_message हो सकता है).

किसी पैकेज के लिए अनाम टारगेट (वह टारगेट जिसका नाम समान है जिसमें डायरेक्ट्री शामिल है) में दी गई सुविधाएं डायरेक्ट्री का नाम. अगर ऐसा कोई टारगेट नहीं है, तो कोई यूनिनाम न बनाएं टारगेट.

किसी मिलते-जुलते टारगेट के बारे में बताते समय, छोटे नाम का इस्तेमाल करना ज़्यादा पसंद है (//x //x:x के बजाय). अगर आप एक ही पैकेज में हैं, तो स्थानीय (//x के बजाय :x).

"रिज़र्व्ड" का इस्तेमाल करने से बचें खास मतलब वाले टारगेट नाम. इसमें ये शामिल हैं all, __pkg__, और __subpackages__, इन नामों के लिए खास है सिमेंटिक्स के बारे में जानकारी. इन चीज़ों का इस्तेमाल करते समय भ्रम की स्थिति और अनचाहे व्यवहार की वजह बन सकती है.

मौजूदा टीम कन्वेंशन के बिना इन कानूनों को मानना ज़रूरी नहीं है जो Google पर ज़्यादा से ज़्यादा इस्तेमाल किए जाते हैं:

  • आम तौर पर, "snake_case" का इस्तेमाल करें
    • src वाले java_library के लिए इसका मतलब ऐसे नाम का इस्तेमाल करना है जो एक्सटेंशन के बिना फ़ाइल नाम के समान है
    • Java *_binary और *_test नियमों के लिए, इसका इस्तेमाल करें "Upper CamelCase". इससे टारगेट का नाम, src में से किसी एक से मैच हो जाता है. इसके लिए java_test, इससे test_class एट्रिब्यूट के लिए टारगेट के नाम से अनुमानित होता है.
  • अगर किसी खास टारगेट के कई वैरिएंट हैं, तो टारगेट के आखिर में सफ़िक्स जोड़ें साफ़ तौर पर बताएं (जैसे कि. :foo_dev, :foo_prod या :bar_x86, :bar_x64)
  • _test, _unittest, Test या Tests वाले _test टारगेट को सफ़िक्स पर लागू करें
  • जब तक ज़रूरी न हो, तब तक _lib या _library जैसे बेकार के सफ़िक्स का इस्तेमाल न करें _library टारगेट और उससे जुड़े _binary के बीच टकराव से बचें)
  • प्रोटो से जुड़े टारगेट के लिए:
    • proto_library टारगेट के नाम _proto से खत्म होने चाहिए
    • अलग-अलग भाषाओं के लिए *_proto_library के नियम, दिए गए नियमों से मेल खाने चाहिए प्रोटो का इस्तेमाल करें, लेकिन _proto को भाषा के हिसाब से सफ़िक्स से बदल दें, जैसे कि:
      • cc_proto_library: _cc_proto
      • java_proto_library: _java_proto
      • java_lite_proto_library: _java_proto_lite

किसको दिखाई दे

ऐक्सेस की अनुमति देते हुए, यह ज़रूरी है कि विज़िबिलिटी का दायरा जितना हो सके उतना सटीक रखा जाए और रिवर्स डिपेंडेंसी के हिसाब से. __pkg__ और __subpackages__ को इस तौर पर इस्तेमाल करें उचित.

default_visibility पैकेज को //visibility:public पर सेट न करें. //visibility:public को केवल इसमें लक्ष्यों के लिए अलग-अलग सेट किया जाना चाहिए प्रोजेक्ट का सार्वजनिक API (एपीआई) शामिल है. ये लाइब्रेरी इस तरह की हो सकती हैं जिन्हें अन्य पर लागू होती है. इसका इस्तेमाल किसी बाहरी प्रोजेक्ट या बाइनरी बिल्ड प्रोसेस शुरू करें.

डिपेंडेंसी

डिपेंडेंसी को डायरेक्ट डिपेंडेंसी पर निर्भर होना चाहिए जो नियम में बताए गए सोर्स के लिए ज़रूरी हैं). ट्रांज़िटिव डिपेंडेंसी को सूची में शामिल न करें.

पैकेज-लोकल डिपेंडेंसी पहले सूची में होनी चाहिए और उनका रेफ़रंस दिया जाना चाहिए कम सुरक्षित मौजूदा पैकेज में टारगेट के रेफ़रंस सेक्शन देखें (उसके पैकेज के नाम के हिसाब से नहीं).

डिपेंडेंसी को एक ही सूची के तौर पर सीधे तौर पर लिस्ट करना है. "सामान्य" शब्द का इस्तेमाल करना एक वैरिएबल में कई टारगेट की डिपेंडेंसी, रखरखाव को कम करती है, टूल के लिए किसी टारगेट की डिपेंडेंसी को बदलना नामुमकिन है. साथ ही, इसकी वजह से इस्तेमाल नहीं की गई डिपेंडेंसी.

ग्लोब

"कोई लक्ष्य नहीं" का संकेत दें [] के साथ. किसी ऐसे ग्लोब का इस्तेमाल न करें जो किसी भी चीज़ से मेल न खाता हो: इसमें गड़बड़ी होने की संभावना ज़्यादा होती है और इसका मतलब खाली सूची की तुलना में कम होता है.

बार-बार होने वाला

सोर्स फ़ाइलों को मैच करने के लिए, बार-बार इस्तेमाल होने वाले ग्लब का इस्तेमाल न करें (उदाहरण के लिए, glob(["**/*.java"])).

बार-बार होने वाले ग्लोब की वजह से BUILD फ़ाइलों को समझना मुश्किल हो जाता है, क्योंकि वे पेज को स्किप कर देते हैं BUILD फ़ाइलों वाली सबडायरेक्ट्री.

BUILD फ़ाइल की तुलना में, बार-बार होने वाले ग्लोब आम तौर पर कम कारगर होते हैं डायरेक्ट्री के अलग-अलग सोर्स के बीच डिपेंडेंसी ग्राफ़ होता है, जिससे यह बेहतर तरीके से रिमोट कैशिंग और समानता.

हर डायरेक्ट्री में BUILD फ़ाइल लिखना और इनके बीच डिपेंडेंसी ग्राफ़ है.

बार-बार नहीं होने वाला

आम तौर पर, नॉन-रिकर्सिव ग्लोब का इस्तेमाल किया जा सकता है.

अन्य कन्वेंशन

  • कॉन्सटेंट की जानकारी देने के लिए, अंग्रेज़ी के बड़े अक्षरों और अंडरस्कोर का इस्तेमाल करें, जैसे कि GLOBAL_CONSTANT, वैरिएबल (जैसे कि my_variable) के बारे में बताने के लिए, लोअरकेस और अंडरस्कोर का इस्तेमाल करें.

  • लेबल को कभी भी बांटा नहीं जाना चाहिए, भले ही वे 79 वर्णों से ज़्यादा लंबे हों. जब भी हो सके, लेबल को स्ट्रिंग की लिटरल वैल्यू होना चाहिए. तथ्यों के हिसाब से: इससे हमें ढूंढना और बदलना आसान है. इससे कॉन्टेंट को पढ़ना भी आसान हो जाता है.

  • नाम विशेषता का मान एक स्थायी स्थिर स्ट्रिंग होना चाहिए (सिवाय मैक्रो में). तथ्यों के हिसाब से: बाहरी टूल नियम. उन्हें कोड समझने की ज़रूरत के बिना ही, नियम तलाशने होते हैं.

  • बूलियन-टाइप एट्रिब्यूट सेट करते समय, बूलियन वैल्यू का इस्तेमाल करें, न कि पूर्णांक वैल्यू का. लेगसी वजहों से, नियम अब भी इंटीजर को ज़रूरत के हिसाब से बूलियन में बदलते हैं, लेकिन इसकी सलाह नहीं दी जाती है. तथ्यों के हिसाब से: flaky = 1 को ऐसा कहा जा सकता है कि इसे गलत तरीके से पढ़ा जा सकता है "इस टारगेट को एक बार फिर से चलाकर, डिफ़ेक करना". flaky = True साफ़ तौर पर कह रहा है "यह टेस्ट सही में नहीं है".

Python स्टाइल गाइड के साथ अंतर

हालांकि, इसके साथ काम करता है Python स्टाइल गाइड कुछ मकसद हैं, तो कुछ अंतर हैं:

  • लाइन की लंबाई की कोई सख्त सीमा नहीं है. लंबी टिप्पणियां और लंबी स्ट्रिंग अक्सर बंटी होती हैं 79 कॉलम तक सीमित नहीं है, लेकिन यह ज़रूरी नहीं है. इसे कोड में लागू नहीं किया जाना चाहिए समीक्षा करने या स्क्रिप्ट पहले से सबमिट करने के लिए किया जा सकता है. तथ्यों के हिसाब से: लेबल लंबे हो सकते हैं और तय सीमा से ज़्यादा भी हो सकते हैं सीमा तय करें. BUILD फ़ाइलों का टूल की मदद से जनरेट होना या उनमें बदलाव करना आम बात है, जो कि लाइन की लंबाई की सीमा के साथ अच्छा नहीं है.

  • इंप्लिसिट स्ट्रिंग को जोड़ने की सुविधा काम नहीं करती. + ऑपरेटर का इस्तेमाल करें. खास जानकारी: BUILD फ़ाइलों में कई स्ट्रिंग की सूचियां होती हैं. यह भूलना आसान है कि कॉमा, जो एक पूर्ण अलग परिणाम पर ले जाता है. इसकी वजह से कई गड़बड़ियां हुई हैं पिछली बार इस सूची में शामिल थे. यह चर्चा भी देखें.

  • नियमों में कीवर्ड आर्ग्युमेंट के लिए, = निशान के आस-पास स्पेस का इस्तेमाल करें. तथ्यों के साथ: Python के मुकाबले, नाम वाले आर्ग्युमेंट ज़्यादा बार इस्तेमाल किए जाते हैं. साथ ही, ये हमेशा अलग करने के लिए. स्पेसेज़ का इस्तेमाल करके, कॉन्टेंट को आसानी से पढ़ा जा सकता है. यह सम्मेलन आस-पास लंबे समय तक बरकरार रहेगा और सभी मौजूदा BUILD फ़ाइलों में बदलाव नहीं किया जा सकता.

  • डिफ़ॉल्ट रूप से, स्ट्रिंग के लिए डबल कोटेशन मार्क का इस्तेमाल करें. तथ्यों की वजह: इसका मतलब नहीं है का इस्तेमाल Python स्टाइल गाइड में किया गया है, लेकिन यह एक जैसा रखने का सुझाव देता है. इसलिए, हम ने केवल डबल-कोट वाली स्ट्रिंग का उपयोग करने का निर्णय लिया. कई भाषाओं में डबल कोट का इस्तेमाल होता है स्ट्रिंग की लिटरल वैल्यू के लिए.

  • दो टॉप लेवल परिभाषाओं के बीच एक खाली लाइन का इस्तेमाल करें. तथ्यों के हिसाब से: BUILD फ़ाइल की बनावट, आम Python फ़ाइल जैसी नहीं है. इसमें सिर्फ़ में दी गई जानकारी शामिल होती है. एक खाली लाइन का इस्तेमाल करने से, BUILD फ़ाइलें छोटी हो जाती हैं.