[ English | 中文 (简体, 中国) | русский | português (Brasil) | नेपाली | 한국어 (대한민국) | Indonesia | français | español | esperanto | English (United Kingdom) | Deutsch ]

Gaya Kode

Sebagai sebuah proyek, Horizon mematuhi standar kualitas kode.

Python

Kami mengikuti PEP8 untuk semua kode Python kami, dan menggunakan pep8.py (tersedia melalui shortcut tox -e pep8) untuk memvalidasi bahwa kode kami memenuhi pedoman gaya Python yang tepat.

Django

Selain itu, kami mengikuti Django's style guide untuk templat, tampilan, dan bermacam-macam lainnya.

JavaScript

Standar berikut ini dibagi menjadi bagian yang diperlukan dan direkomendasikan. Tujuan utama kami dalam menetapkan praktik terbaik ini adalah memiliki kode yang dapat diandalkan, dapat dibaca, dan dipelihara.

Wajib

Reliable

  • Kode tersebut harus berfungsi pada browser web Firefox, Chrome, Safari, dan Opera versi stabil dan terbaru, dan pada Microsoft Internet Explorer 11 dan yang lebih baru.

  • Jika Anda mematikan kompresi selama pengembangan melalui COMPRESS_ENABLED = False di local_settings.py, aktifkan kembali kompresi dan uji kode Anda sebelum mengirim.

  • Gunakan === sebagai lawan dari == untuk pemeriksaan kesetaraan. == akan melakukan casting jenis sebelum membandingkan, yang dapat menyebabkan hasil yang tidak diinginkan.

    Catatan

    Jika typecasting diinginkan, casting eksplisit lebih disukai untuk menjaga makna kode Anda tetap jelas.

  • Simpan reflow dokumen seminimal mungkin. Manipulasi DOM mahal, dan bisa menjadi masalah kinerja. Jika Anda mengakses DOM, pastikan Anda melakukannya dengan cara yang paling optimal. Salah satu contoh adalah untuk membangun fragmen dokumen dan kemudian menambahkan fragmen ke DOM dalam satu pass sebagai ganti melakukan beberapa pembaruan DOM yang lebih kecil.

  • Gunakan "strict", sertakan setiap file JavaScript di dalam fungsi yang dapat dieksekusi sendiri. Fungsi self-executing menjaga scoped ketat untuk file, sehingga variabel dan metode tidak terpapar ke file JavaScript lain dalam produk.

    Catatan

    Menggunakan strict akan memberikan pengecualian untuk kesalahan pengkodean umum, seperti mengakses var global, yang biasanya tidak ditandai.

    Contoh:

    (function(){
      'use strict';
      // code...
    })();
    
  • Gunakan forEach | each masing-masing`` saat perulangan jika memungkinkan. AngularJS dan jQuery keduanya menyediakan untuk setiap loop yang menyediakan iterasi dan ruang lingkup.

    AngularJS:

    angular.forEach(objectToIterateOver, function(value, key) {
      // loop logic
    });
    

    jQuery:

    $.each(objectToIterateOver, function(key, value) {
      // loop logic
    });
    
  • Jangan letakkan variabel atau fungsi di namespace global. Ada beberapa alasan mengapa global buruk, salah satunya adalah bahwa semua JavaScript yang disertakan dalam aplikasi berjalan dalam cakupan yang sama. Masalahnya adalah jika skrip lain memiliki metode atau nama variabel yang sama, mereka saling menimpa.

  • Selalu letakkan var di depan variabel Anda. Tidak menempatkan var di depan suatu variabel menempatkan variabel itu ke dalam ruang global, lihat di atas.

  • Jangan gunakan `` eval () ``. Eval (expression) mengevaluasi ekspresi yang diberikan padanya. Ini dapat membuka kode Anda untuk kerentanan keamanan dan masalah lainnya.

  • Jangan gunakan 'with object {code}'. Pernyataan with digunakan untuk mengakses properti dari suatu objek. Masalah dengan with adalah bahwa eksekusinya tidak konsisten, jadi dengan membaca pernyataan dalam kode itu tidak selalu jelas bagaimana itu digunakan.

Readable & Maintainable

  • Berikan nama yang bermakna untuk metode dan variabel.

  • Hindari bersarang (nesting) berlebihan.

  • Hindari HTML dan CSS dalam kode JS. HTML dan CSS masing-masing termasuk dalam template dan stylesheet. Sebagai contoh:

    • Dalam file HTML kita, kita harus fokus pada tata letak.

      1. Kurangi elemen small/random <script> dan `` <style> `` dalam HTML.

      2. Hindari gaya in-lining menjadi elemen dalam HTML. Gunakan atribut dan kelas sebagai gantinya.

    • Dalam file JS kami, kami harus fokus pada logika daripada mencoba untuk manipulate/style elemen.

      1. Hindari pernyataan seperti ``element.css ({property1, property2 ...}) `` mereka termasuk dalam kelas CSS.

      2. Hindari pernyataan seperti $("<div><span>abc</span></div>") mereka termasuk dalam file template HTML. Gunakan show | hide | clone element jika konten dinamis diperlukan.

      3. Hindari menggunakan kelas untuk tujuan deteksi saja, sebaliknya, tunduk pada atribut. Sebagai contoh untuk menemukan div:

        <div class="something"></div>
          $(".something").html("Don't find me this way!");
        

        lebih baik ditemukan seperti:

        <div data-something></div>
          $("div[data-something]").html("You found me correctly!");
        
  • Hindari kode komentar.

  • Hindari kode mati.

Performance

  • Hindari membuat instance dari objek yang sama berulang kali dalam cakupan yang sama. Sebagai gantinya, tetapkan objek ke variabel dan gunakan kembali objek yang ada. Sebagai contoh:

    $(document).on('click', function() { /* do something. */ });
    $(document).on('mouseover', function() { /* do something. */ });
    

    Pendekatan yang lebih baik:

    var $document = $(document);
    $document.on('click', function() { /* do something. */ });
    $document.on('mouseover', function() { /* do something. */ });
    

    Dalam pendekatan pertama objek jQuery untuk document dibuat setiap kali. Pendekatan kedua hanya membuat satu objek jQuery dan menggunakannya kembali. Setiap objek harus dibuat, menggunakan memori, dan perlu dikumpulkan.

AngularJS

Catatan

Bagian ini dimaksudkan sebagai pengantar cepat untuk berkontribusi dengan AngularJS. Untuk informasi lebih rinci, periksa Panduan Topik AngularJS.

"John Papa Style Guide"

The John Papa Style Guide adalah titik acuan utama untuk gaya kode Angular. Panduan gaya ini telah disahkan oleh tim AngularJS:

"The most current and detailed Angular Style Guide is the
community-driven effort led by John Papa and Todd Motto."

- http://angularjs.blogspot.com/2014/02/an-angularjs-style-guide-and-best.html

Panduan style ditemukan di lokasi di bawah ini:

https://github.com/johnpapa/angular-styleguide

Saat mengulas / menulis, silakan merujuk ke bagian panduan ini. Jika ada masalah, catat dengan komentar dan berikan tautan kembali ke masalah tertentu. Misalnya, kode harus menggunakan fungsi bernama. Peninjauan yang mencatat ini harus menyediakan tautan berikut dalam komentar:

https://github.com/johnpapa/angular-styleguide#style-y024

Selain John Papa, pedoman berikut ini dibagi menjadi bagian yang diperlukan dan direkomendasikan.

Wajib

  • Cakupan bukan model (model adalah Objek JavaScript Anda). Lingkup referensi model. Gunakan ruang lingkup isolasi sedapat mungkin.

  • Karena Django sudah menggunakan {{ }}, use {$ $} or {% verbatim %} sebagai gantinya.

ESLint

ESLint adalah alat yang hebat untuk digunakan selama pengeditan kode Anda untuk meningkatkan kualitas JavaScript dengan memeriksa kode Anda terhadap daftar cek yang dapat dikonfigurasi. Oleh karena itu, pengembang JavaScript harus mengonfigurasi editor mereka untuk menggunakan ESLint untuk memperingatkan mereka tentang kesalahan semacam itu sehingga dapat diatasi. Karena ESLint memiliki banyak opsi konfigurasi untuk dipilih, tautan disediakan di bawah ini untuk opsi yang ingin ditegakkan Horizon bersama dengan instruksi untuk menyiapkan ESLint untuk Eclipse, Sublime Text, Notepad ++ dan WebStorm / PyCharm.

Instruksi untuk pengaturan ESLint: ESLint setup instructions

Catatan

ESLint adalah bagian dari pengujian unit otomatis yang dilakukan oleh Jenkins. Pengujian otomatis menggunakan konfigurasi default, yang kurang ketat dari konfigurasi yang kami sarankan untuk dijalankan di lingkungan pengembangan lokal Anda.

CSS

Pedoman gaya untuk CSS saat ini sangat minim. Lakukan yang terbaik untuk membuat kode dapat dibaca dan diatur dengan baik. Dua spasi lebih disukai untuk indentasi agar sesuai dengan file JavaScript dan HTML.

Perpustakaan JavaScript dan CSS menggunakan xstatic

Kami tidak membundel kode pihak ketiga di pohon sumber Horizon. Sebagai gantinya, kami mengemas file yang diperlukan sebagai paket Python xstatic dan menambahkannya sebagai dependensi ke Horizon.

Untuk membuat paket xstatic baru:

  1. Periksa apakah perpustakaan sudah dikemas sebagai xstatic di PyPi, dengan mencari nama perpustakaan. Jika sudah, lanjutkan ke langkah 5. Jika ya, tetapi tidak pada versi yang benar, hubungi pembuat paket asli untuk meminta mereka memperbaruinya.

  2. Kemas perpustakaan sebagai paket xstatic dengan mengikuti instruksi dalam dokumentasi xstatic. Instal skrip xstatic-release dan ikuti instruksi yang menyertainya.

  3. Create a new repository under OpenStack. Gunakan grup "xstatic-core" dan "xstatic-ptl" untuk ACL. Pastikan untuk menyertakan pekerjaan -pypi-wheel-upload dalam konfigurasi proyek.

  4. Set up PyPi untuk mengizinkan OpenStack (pengguna "openstackci") untuk mempublikasikan paket Anda.

  5. Tambahkan paket baru ke global-requirements.

Untuk membuat rilis baru paket, Anda perlu:

  1. Pastikan informasi versi dalam file xstatic/pkg/<package name>/__init__.py adalah yang terbaru, terutama` BUILD`.

  2. Dorong paket Anda yang diperbarui untuk ditinjau di gerrit.

  3. Once the review is approved and the change merged, request a release by updating or creating the appropriate file for the xstatic package in the releases repository under deliverables/_independent. That will cause it to be automatically packaged and released to PyPi.

Peringatan

Perhatikan bahwa setelah sebuah paket dirilis, Anda tidak dapat "un-release". Anda tidak boleh mencoba untuk memodifikasi, menghapus atau mengganti nama paket yang dirilis tanpa banyak perencanaan dan umpan balik yang cermat dari semua proyek yang menggunakannya.

Untuk memperbaiki kesalahan pengemasan, xstatic memiliki mekanisme build number. Cukup perbaiki kesalahan, tambahkan nomor build dan lepaskan paket yang lebih baru.

Mengintegrasikan paket xstatic baru ke Horizon

Setelah melakukan rilis paket xstatic:

  1. Look for the upper-constraints.txt edit related to the xstatic release that was just performed. One will be created automatically by the release process in the openstack/requirements project with the topic new-release. You should -1 that patch until you are confident Horizon does not break (or you have generated a patch to fix Horizon for that release.) If no upper-constraints.txt patch is automatically generated, ensure the releases yaml file created in the releases repository has the "include-pypi-link: yes" setting.

  2. Tarik patch itu ke bawah sehingga Anda memiliki file upper-constraints.txt yang diedit secara lokal.

  3. Set the environment variable TOX_CONSTRAINTS_FILE to the edited upper-constraints.txt file name and run tests or local development server through tox. This will pull in the precise version of the xstatic package that you need.

  4. Jalan terus ke release setelah Anda menyukai perubahan Horizon stabil.

Release versi Horizon baru yang kompatibel untuk mengatasi masalah dalam rilis xstatic baru:

  1. Lanjutkan ke -1 patch upper-constraints.txt di atas hingga proses ini selesai. +1 dari pengembang Horizon akan menunjukkan kepada tim persyaratan bahwa patch upper-constraints.txt OK untuk bergabung.

  2. Saat mengirimkan perubahan Anda ke Horizon untuk mengatasi masalah seputar rilis xstatic baru, gunakan Depends-On: merujuk ulasan upper-constraints.txt. Ini akan menyebabkan infrastruktur pengujian OpenStack menarik paket xstatic Anda yang diperbarui juga.

  3. Gabungkan patch upper-constraints.txt dan patch Horizon dengan memperhatikan bahwa gerbang Horizon dapat dipatahkan untuk sementara di antara langkah-langkah ini, jadi cobalah untuk meminimalkan penundaan di sana. Dengan Depends-On, sebenarnya aman untuk +W patch Horizon, yang akan ditahan hingga penggabungan patch upper-constraints.txt terkait.

  4. Setelah patch upper-constraints.txt bergabung, Anda harus mengusulkan patch untuk global-requirement yang menambrak versi minimum paket hingga versi upper-constraint sehingga penyebar/pembuat paket yang tidak menerima upper-constraint masih bisa kompatibel dengan versi paket.

HTML

Sekali lagi, keterbacaan adalah yang terpenting; Namun berhati-hatilah dengan bagaimana browser akan menangani spasi ketika rendering output. Dua spasi adalah gaya lekukan yang disukai untuk mencocokkan semua kode front-end.

Penanganan Kekecualian

Hindari mempropagandakan pesan pengecualian langsung yang dilemparkan oleh OpenStack APIs ke UI. Ini adalah tindakan pencegahan agar tidak memberikan data yang tidak jelas atau sensitif kepada pengguna. Pesan kesalahan dari API ini juga tidak dapat diterjemahkan. Sampai ada kerangka kerja penanganan kesalahan standar yang diterapkan oleh layanan yang menyajikan pesan yang bersih dan diterjemahkan, horizon menangkap semua pengecualian yang dilemparkan oleh API dan menormalkannya dalam horizon.exceptions.handle().

Dokumentasi

Dokumentasi Horizon ditulis dalam reStructuredText (reST) dan menggunakan Sphinx untuk parsing dan fungsionalitas tambahan, dan harus mengikuti praktik standar untuk menulis REST. Ini termasuk:

  • Alur paragraf sedemikian rupa sehingga garis-garis membungkus pada 80 karakter atau kurang.

  • Gunakan tata bahasa, ejaan, huruf besar, dan tanda baca yang benar setiap saat.

  • Manfaatkan fitur autodoc Sphinx untuk mendokumentasikan modul, kelas, dan fungsi. Ini membuat dokumen dekat dengan sumbernya.

  • Jika memungkinkan, gunakan sintaks cross-reference Sphinx (misal :class:`~horizon.foo.Bar) ketika merujuk ke komponen Horizon lainnya. Semakin baik tautannya dokumen kami, semakin mudah digunakan.

Pastikan untuk membuat dokumentasi sebelum mengirimkan patch untuk ditinjau. Peringatan yang tidak terduga sering muncul ketika membuat dokumentasi, dan sedikit kesalahan sintaks ulang sering menyebabkan tautan atau rujukan silang tidak berfungsi dengan benar.

Dokumentasi dibuat dengan Sphinx menggunakan perintah tox. Untuk membuat dokumen HTML dan halaman manual:

$ tox -e docs

Hasilnya masing-masing dalam direktori doc/build/html dan doc/build/man.

Konvensi

Cukup dengan konvensi, kami memiliki beberapa aturan tentang penamaan:

  • Istilah "project" digunakan sebagai ganti terminologi "tenant" Keystone di semua teks yang menghadap pengguna. Istilah "tenant" masih digunakan dalam kode API untuk membuat hal-hal lebih jelas bagi pengembang.

  • Istilah "dashboard" mengacu pada kelas dasbor tingkat atas, dan "panel" ke sub-item dalam dasbor. Mengacu pada panel sebagai dasbor membingungkan dan salah.