নির্মাণ শৈলী গাইড

BUILD ফাইল ফরম্যাটিং Go এর মতো একই পদ্ধতি অনুসরণ করে, যেখানে একটি প্রমিত টুল বেশিরভাগ ফর্ম্যাটিং সমস্যাগুলির যত্ন নেয়। বিল্ডিফায়ার হল একটি টুল যা একটি স্ট্যান্ডার্ড স্টাইলে সোর্স কোড পার্স করে এবং নির্গত করে। প্রতিটি 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 , অথবা DirectMessage.java এর জন্য একটি java_library chat.cc নাম direct_message যেতে পারে)।

একটি প্যাকেজের জন্য eponymous টার্গেট (ধারিত ডিরেক্টরির মতো একই নামের লক্ষ্য) ডিরেক্টরির নামের দ্বারা বর্ণিত কার্যকারিতা প্রদান করা উচিত। যদি এই ধরনের কোন লক্ষ্য না থাকে, তাহলে একটি নামীয় লক্ষ্য তৈরি করবেন না।

একটি eponymous টার্গেট ( //x //x:x ) উল্লেখ করার সময় সংক্ষিপ্ত নাম ব্যবহার করতে পছন্দ করুন। আপনি যদি একই প্যাকেজে থাকেন তবে স্থানীয় রেফারেন্স পছন্দ করুন ( :x এর পরিবর্তে //x )।

বিশেষ অর্থ আছে এমন "সংরক্ষিত" টার্গেট নাম ব্যবহার করা এড়িয়ে চলুন। এর মধ্যে রয়েছে all , __pkg__ , এবং __subpackages__ , এই নামগুলির বিশেষ শব্দার্থ আছে এবং সেগুলি ব্যবহার করার সময় বিভ্রান্তি এবং অপ্রত্যাশিত আচরণের কারণ হতে পারে।

একটি প্রচলিত টিম কনভেনশনের অনুপস্থিতিতে এইগুলি হল কিছু অ-বাধ্যতামূলক সুপারিশ যা Google-এ ব্যাপকভাবে ব্যবহৃত হয়:

• সাধারণভাবে, "snake_case" ব্যবহার করুন
  • একটি src সহ একটি java_library জন্য এর অর্থ হল এমন একটি নাম ব্যবহার করা যা এক্সটেনশন ছাড়া ফাইলের নামের মতো নয়
  • Java *_binary এবং *_test নিয়মের জন্য, "Upper CamelCase" ব্যবহার করুন। এটি লক্ষ্যের নামের একটি src s এর সাথে মেলে। java_test এর জন্য, এটি test_class অ্যাট্রিবিউটের জন্য লক্ষ্যের নাম থেকে অনুমান করা সম্ভব করে তোলে।
• যদি একটি নির্দিষ্ট লক্ষ্যের একাধিক রূপ থাকে তবে দ্ব্যর্থহীন করার জন্য একটি প্রত্যয় যুক্ত করুন (যেমন :foo_dev , :foo_prod বা :bar_x86 , :bar_x64 )
• প্রত্যয় _test , _unittest , Test , or 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 flaky = 1 "এই টার্গেটটিকে একবার পুনরায় চালু করে ডিফ্লেক করুন" বলে ভুল পড়া যেতে পারে। flaky = True দ্ব্যর্থহীনভাবে বলে "এই পরীক্ষাটি ফ্ল্যাকি"।

পাইথন স্টাইল গাইডের সাথে পার্থক্য

যদিও পাইথন স্টাইল গাইডের সাথে সামঞ্জস্যতা একটি লক্ষ্য, তবে কয়েকটি পার্থক্য রয়েছে:

• কোন কঠোর লাইন দৈর্ঘ্য সীমা. দীর্ঘ মন্তব্য এবং দীর্ঘ স্ট্রিংগুলি প্রায়ই 79টি কলামে বিভক্ত হয়, তবে এটির প্রয়োজন হয় না। এটি কোড পর্যালোচনায় প্রয়োগ করা উচিত নয় বা স্ক্রিপ্ট জমা দেওয়া উচিত নয়। যুক্তি : লেবেল দীর্ঘ হতে পারে এবং এই সীমা অতিক্রম করতে পারে। BUILD ফাইলগুলি তৈরি করা বা সরঞ্জাম দ্বারা সম্পাদনা করা সাধারণ, যা একটি লাইন দৈর্ঘ্যের সীমার সাথে ভাল যায় না।

• অন্তর্নিহিত স্ট্রিং সংযোগ সমর্থিত নয়। + অপারেটর ব্যবহার করুন। যুক্তি : BUILD ফাইলে অনেক স্ট্রিং তালিকা থাকে। একটি কমা ভুলে যাওয়া সহজ, যা একটি সম্পূর্ণ ভিন্ন ফলাফলের দিকে নিয়ে যায়। এটি অতীতে অনেক বাগ তৈরি করেছে। এছাড়াও এই আলোচনা দেখুন.

• নিয়মে কীওয়ার্ড আর্গুমেন্টের জন্য = চিহ্নের চারপাশে স্পেস ব্যবহার করুন। যুক্তি: নামযুক্ত আর্গুমেন্টগুলি পাইথনের তুলনায় অনেক বেশি ঘন ঘন এবং সর্বদা একটি পৃথক লাইনে থাকে। স্পেস পঠনযোগ্যতা উন্নত করে। এই কনভেনশনটি দীর্ঘকাল ধরে চলছে, এবং এটি বিদ্যমান সমস্ত BUILD ফাইল সংশোধন করার মতো নয়।

• ডিফল্টরূপে, স্ট্রিংগুলির জন্য ডবল উদ্ধৃতি চিহ্ন ব্যবহার করুন। যুক্তি : এটি পাইথন স্টাইল গাইডে নির্দিষ্ট করা নেই, তবে এটি ধারাবাহিকতার সুপারিশ করে। তাই আমরা শুধুমাত্র ডবল উদ্ধৃত স্ট্রিং ব্যবহার করার সিদ্ধান্ত নিয়েছে. অনেক ভাষা স্ট্রিং লিটারেলের জন্য ডাবল-উদ্ধৃতি ব্যবহার করে।

• দুটি শীর্ষ-স্তরের সংজ্ঞার মধ্যে একটি একক ফাঁকা লাইন ব্যবহার করুন। যুক্তি : একটি BUILD ফাইলের গঠন একটি সাধারণ পাইথন ফাইলের মতো নয়। এটি শুধুমাত্র শীর্ষ স্তরের বিবৃতি আছে. একটি একক-খালি লাইন ব্যবহার করা BUILD ছোট করে তোলে।