Piawaian Pengaturcaraan Javascript Dojo Seragamkan penulisan JavaScript anda sendiri_Pengetahuan asas

Kata Pengantar

Kebaikan tabiat menulis JavaScript yang baik adalah jelas pada hari ini Bingo mengesyorkan spesifikasi pengaturcaraan Dojo Javascript kepada semua orang Ia adalah spesifikasi gaya pengaturcaraan Javascript yang sangat baik. Terima kasih kepada i.feelinglucky untuk terjemahan.

Prekata

Sebarang pelanggaran panduan ini dibenarkan jika ia meningkatkan kebolehbacaan.

Semua kod hendaklah dipermudahkan untuk dibaca oleh orang lain.

Rujukan Bacaan Pantas

API Teras Sila gunakan gaya berikut:

结构	规则	注释
模块	小写	不要使用多重语义（Never multiple words）
类	骆驼
公有方法	混合	其他的外部调用也可以使用 lower_case()，这样的风格
公有变量	混合
常量	骆驼 或 大写

Struktur

Peraturan

Ulasan

结构	规则
私有方法	混合，例子：_mixedCase
私有变量	混合，例子：_mixedCase
方法（method）参数	混合，例子：_mixedCase, mixedCase
本地（local）变量	混合，例子：_mixedCase, mixedCase

Modul huruf kecil Jangan sekali-kali berbilang perkataan Kelas Unta Kaedah awam Campuran Panggilan luaran lain juga boleh menggunakan huruf_kecil(), gaya ini Pembolehubah awam Campuran Malar Unta atau modal Walaupun perkara berikut tidak perlu, ia disyorkan: _mixedCase

Pembolehubah peribadi	Campuran, contoh: _mixedCase
Parameter kaedah	Campuran, contoh: _mixedCase, mixedCase
Pembolehubah setempat (tempatan)	Campuran, contoh: _mixedCase, mixedCase

Konvensyen penamaan

1. Nama pembolehubah mestilah huruf kecil.
2. Penamaan kelas menggunakan peraturan penamaan unta, contohnya:

Akaun, EventHandler

3. Pemalar mesti diisytiharkan di hadapan objek (kelas) atau pembolehubah penghitungan. Pembolehubah penghitungan mesti dinamakan dengan makna praktikal dan ahlinya mesti menggunakan peraturan penamaan unta atau menggunakan huruf besar:

Salin kod Kod adalah seperti berikut:

var NodeTypes = {
Elemen: 1,
DOKUMEN: 2
}

4. Perkataan yang disingkatkan tidak boleh menggunakan nama huruf besar sebagai nama pembolehubah:

getInnerHtml(), getXml(), XmlDocument
5. Perintah kaedah mestilah kata kerja atau frasa kerja:

obj.getSomeValue()
6. Kelas awam mesti dinamakan menggunakan nama campuran (mixedCase).
7. Pembolehubah CSS mesti dinamakan menggunakan pembolehubah kelas awam yang sama yang sepadan dengannya.
8. Ahli atribut pembolehubah kelas persendirian mesti dinamakan dengan nama bercampur (mixedCase) dan didahului dengan garis bawah (_). Contohnya:

Salin kod Kod adalah seperti berikut:

var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}

9 Jika pembolehubah ditetapkan sebagai peribadi, garis bawah mesti ditambah di hadapannya.

ini._somePrivateVariable = pernyataan;

10 Pembolehubah universal mesti menggunakan nama jenis yang konsisten dengan nama mereka:

setTopic(topic) // Topik pembolehubah ialah pembolehubah jenis Topik
11. Semua nama pembolehubah mesti menggunakan nama Inggeris.
12. Jika pembolehubah mempunyai skop yang lebih luas (skop besar), pembolehubah global mesti digunakan dalam kes ini, ia boleh direka bentuk sebagai ahli kelas. Sebaliknya, jika skopnya kecil atau pembolehubah adalah peribadi, gunakan penamaan perkataan yang ringkas.
13. Jika pembolehubah mempunyai nilai pulangan tersiratnya sendiri, elakkan menggunakan kaedah yang serupa:

getHandler(); // Elakkan menggunakan getEventHandler()

14 Pembolehubah awam mesti menyatakan dengan jelas atribut mereka sendiri untuk mengelakkan makna perkataan yang samar-samar, contohnya:

MouseEventHandler
, bukan MseEvtHdlr.
Sila beri perhatian kepada peraturan ini sekali lagi, faedah berbuat demikian sangat jelas. Ia boleh menyatakan dengan jelas maksud yang ditakrifkan oleh ungkapan tersebut. Contohnya:

dojo.events.mouse.Handler // bukannya dojo.events.mouse.MouseEventHandler

15. Kelas/pembina boleh dinamakan dengan memanjangkan nama kelas asasnya, supaya nama kelas asasnya boleh ditemui dengan betul dan cepat:
Pengendali Acara
UIEventHandler
MouseEventHandler
Kelas asas boleh memendekkan penamaannya pada premis menerangkan sifatnya dengan jelas:
​MouseEventHandler berbanding MouseUIEventHandler.

Konvensyen penamaan khas

Istilah "get/set" tidak boleh dikaitkan dengan medan melainkan ia ditakrifkan sebagai pembolehubah persendirian.
Nama pembolehubah yang didahului oleh "adalah" hendaklah nilai Boolean, dan begitu juga ia boleh menjadi "mempunyai", "boleh" atau "sepatutnya".
Istilah "kira" sebagai nama pembolehubah harus merujuk kepada pembolehubah yang telah dikira.
Istilah "cari" sebagai nama pembolehubah hendaklah merujuk kepada pembolehubah yang cariannya telah selesai.
Istilah "memulakan" atau "init" sebagai nama pembolehubah harus merujuk kepada kelas atau jenis pembolehubah lain yang telah dimulakan (dimulakan).
Pembolehubah kawalan UI (Antara Muka Pengguna) harus mempunyai jenis kawalan selepas nama, contohnya: leftComboBox, TopScrollPane.
Bentuk jamak WAJIB digunakan untuk menamakan koleksi.
Nama pembolehubah yang bermula dengan "num" atau "count" adalah nombor konvensional (objek).
Adalah disyorkan untuk menggunakan pembolehubah dengan nama seperti "i", "j", "k" (dan seterusnya) untuk pembolehubah berulang.
Istilah tambahan mesti menggunakan perkataan tambahan, seperti: dapatkan/set, tambah/buang, buat/musnah, mula/henti, sisip/padam, mula/tamat, dsb.
Gunakan singkatan untuk nama yang boleh disingkatkan.
Elakkan nama pembolehubah Boolean yang samar-samar, contohnya:
isNotError, isNotFound adalah haram
Adalah disyorkan untuk menambah "Pengecualian" atau "Ralat" selepas nama pembolehubah untuk kelas ralat.
Jika kaedah mengembalikan kelas, nama harus menunjukkan apa yang dikembalikan jika ia adalah prosedur, ia harus menunjukkan apa yang dilakukannya.

Fail

Sila gunakan 4 hentian tab ruang putih untuk lekukan.
Jika editor anda menyokong teg fail, sila tambah baris berikut untuk menjadikan kod kami lebih mudah dibaca:

// vim:ts=4:noet:tw=0:
Nota terjemahan: Warga asing menggunakan editor VIM lebih banyak, anda boleh memilih untuk mengikuti artikel ini.

Lipatan kod mesti kelihatan lengkap dan logik:

Salin kod Kod adalah seperti berikut:

var someExpression = Ungkapan1
Ungkapan2
Ungkapan3;

var o = someObject.get(
Ungkapan1,
Ungkapan2,
Ungkapan3
);

Nota: Lekukan ungkapan dan pengisytiharan pembolehubah hendaklah konsisten.
Nota: Parameter fungsi hendaklah diinden secara eksplisit dan peraturan lekukan harus konsisten dengan blok lain.

Pembolehubah

1. Pembolehubah mesti diisytiharkan dan dimulakan sebelum ia boleh digunakan, walaupun ia adalah jenis NULL.
2. Pembolehubah tidak boleh samar-samar.
3. Set pembolehubah yang berkaitan hendaklah diletakkan dalam blok kod yang sama dan set pembolehubah yang tidak berkaitan tidak boleh diletakkan dalam blok kod yang sama.
4. Pembolehubah harus cuba mengekalkan jangka hayat minimum.
5. Spesifikasi untuk pembolehubah gelung/berulang:
   1. Jika anda hanya mempunyai blok kawalan gelung, anda mesti menggunakan gelung FOR.
   2. Pembolehubah gelung hendaklah dimulakan sebelum gelung bermula; jika menggunakan gelung FOR, gunakan pernyataan FOR untuk memulakan pembolehubah gelung.
   3. Pernyataan “buat … sementara” dibenarkan.
   4. Pernyataan "break" dan "continue" masih dibenarkan (tetapi harap maklum).
6. Ungkapan bersyarat
   1. Ungkapan bersyarat kompleks harus dielakkan sebanyak mungkin dan pembolehubah Boolean sementara boleh digunakan jika perlu.
   2. Huruf nominal HARUS diletakkan di bahagian “jika” dan pengecualian di bahagian “lain” dalam pernyataan “jika”.
   3. Sekatan dalam ungkapan bersyarat harus dielakkan.
7. Pelbagai
   1. Cuba elakkan nombor ajaib, ia harus digantikan dengan pemalar.
   2. Pembolehubah titik terapung mesti menyatakan satu tempat perpuluhan (walaupun 0).
   3. Pembolehubah titik terapung mesti menyatakan bahagian sebenar, walaupun ia adalah sifar (gunakan 0 pendahuluan).

Reka letak

Sekat

Coretan kod biasa sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

semasa (!selesai){
doSomething();
isDone = moreToDo();
}

JIKA kenyataan sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

jika (sesuatu Syarat){
kenyataan;
} lain jika (someLainCondition){
kenyataan;
} lain {
kenyataan;
}

Pernyataan FOR sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

untuk (permulaan; syarat; kemas kini){
kenyataan;
}

SEDANGKAN kenyataan sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

manakala (!selesai) {
doSomething();
isDone = moreToDo();
}

LAKUKAN … SEDANGKAN kenyataan sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

lakukan {
kenyataan;
} manakala (syarat);

Pernyataan SWITCH sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

suis (keadaan) {
kes ABC:
kenyataan;
// gagal
kes DEF:
kenyataan;
rehat;
lalai:
kenyataan;
rehat;
}

Pernyataan TRY … CATCH sepatutnya kelihatan seperti ini:

Salin kod Kod adalah seperti berikut:

cuba {
kenyataan;
} tangkap(cth) {
kenyataan;
} akhirnya {
kenyataan;
}

Baris tunggal IF – ELSE, WHILE atau FOR pernyataan juga mesti mempunyai kurungan, tetapi ia boleh ditulis seperti ini:
jika (syarat){ pernyataan; manakala (syarat){ pernyataan; untuk (permulaan; syarat; kemas kini){ pernyataan;
Kosong

Operator

disyorkan untuk dipisahkan oleh ruang (termasuk operator ternary).

Elakkan menggunakan ruang putih untuk memisahkan kata kunci berikut:
pecah
2. tangkap
   teruskan
   buat
   lain
   akhirnya
   untuk
   fungsi (jika ia adalah fungsi tanpa nama, contohnya: var foo = function(){}; )
   jika
   kembali
   suis
   ini
   cuba
   batal
   sementara
   dengan
   Kata kunci berikut mesti dipisahkan dengan ruang kosong:
kes
3. lalai
   padam
   fungsi (jika ia adalah pengisytiharan, contohnya: function foo(){}; )
   dalam
   contoh
   baharu
   buang
   jenis
   var
   Koma (,) disyorkan untuk dipisahkan dengan ruang putih.
Kolon (:) Adalah disyorkan untuk menggunakan ruang putih untuk memisahkan.
Titik (.) di hujung disyorkan untuk dipisahkan oleh ruang putih.
Titik (.) Elakkan menggunakan ruang putih di hadapan.
Panggilan fungsi dan kaedah elakkan menggunakan ruang kosong, contohnya: doSomething(someParameter); // bukannya doSomething (someParameter)
Gunakan garisan kosong antara blok logik.
Penyata disyorkan supaya diselaraskan supaya lebih mudah dibaca.
10. Nota

Kod jerky

1. Tidak perlu tambah komen Mula-mula anda perlu menulis semula Mereka. Sila gunakan bahasa Inggeris untuk semua komen. Daripada penyelesaian yang diselesaikan kepada ciri yang belum diterokai, ulasan
2. mestilah
3. berkaitan dengan kod. Selepas sejumlah besar pengisytiharan berubah
mestilah
4. diikuti dengan ulasan. Ulasan perlu menerangkan kegunaan coretan kod, terutamanya coretan kod berikut. Ulasan
5. Tidak perlu menambah
6. pada setiap baris. Dokumentasi

Yang berikut menyediakan beberapa fungsi asas atau kaedah penerangan objek: Ringkasan: Terangkan secara ringkas tujuan fungsi atau objek ini

Penerangan: Penerangan ringkas tentang fungsi atau kelas ini

Pulangan: Menerangkan perkara yang dikembalikan oleh fungsi ini (tidak termasuk jenis pemulangan)

Maklumat fungsi asas

Salin kod

Kod adalah seperti berikut: fungsi(){ // ringkasan: Tidak lama lagi kita akan mempunyai harta yang cukup untuk memerintah seluruh New Jersey.

// penerangan: Atau kita boleh dapatkan rakan sebilik yang baharu.

// Lihat, kamu pergi cari dia. Dia tidak menjerit pada kamu.
// Apa yang saya cuba lakukan ialah membuat dia tersenyum dan menyanyi di sekeliling
// dia dan menari di sekelilingnya dan dia hanya berbaring dengan saya.
// Dia menyuruh saya masuk ke peti sejuk kerana ada karnival di sana.
// kembali: Lihat, pita Bananarama!
}



Maklumat fungsi objek

Tiada perihalan nilai pulangan

Salin kod

Kod adalah seperti berikut:

{
// ringkasan: Dingle, gunakan mesin pelangi!
// penerangan:
// Beritahu anda apa, saya harap saya--ya ampun--pancaran itu,
// datang seperti itu, kelajuannya, anda mungkin mahu menyesuaikannya.
// Ia benar-benar mempunyai nombor di belakang saya, maksud saya, dan saya tidak
// nak cakap cambuk, dulu, sebab itu terlalu jauh,
// tetapi, anda diinsuranskan, bukan?
}

Pengisytiharan fungsi

Dalam sesetengah kes, panggilan fungsi dan pengisytiharan tidak kelihatan. Dalam kes ini, kami tidak mempunyai cara untuk menambah arahan, dsb. (untuk program memanggil) dalam fungsi. Jika anda menghadapi situasi ini, anda boleh menggunakan kelas untuk merangkum fungsi.

Nota: Kaedah ini hanya boleh digunakan apabila fungsi tidak mempunyai parameter yang dimulakan. Jika tidak, mereka tidak diendahkan.

Salin kod Kod adalah seperti berikut:

dojo.declare(
"foo",
null,
{
// ringkasan: Fuh, ini pasti menenangkan, Frylock.
// penerangan:
//Beribu-ribu tahun yang lalu, sebelum fajar
// lelaki seperti yang kami kenali, ada Sir Santa of Claus: an
// makhluk seperti beruk membuat mainan kasar dan sia-sia
// tulang dino, melemparkannya ke arah makhluk seperti cimpanzi dengan
// tangan berkedut tanpa mengira bagaimana mereka berkelakuan
// tahun sebelumnya.
// kembali: Melainkan Carl memberi penghormatan kepada Orang Tua Bunian di angkasa.
}
);

Parameter

1. Jenis ringkas
   Parameter jenis mudah boleh dianotasi terus dalam definisi parameter fungsi.
   [cc lang="javascript"]function(/*String*/ foo, /*int*/ bar)...
   Parameter jenis boleh ubah
   Berikut adalah beberapa pengubah suai untuk rujukan:
   ? Parameter pilihan
   … Mengatakan bahawa julat parameter mi tidak pasti
   Susunan
   function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
   Perihalan parameter global
   Jika anda ingin menambah penerangan, anda boleh mengalihkannya ke blok permulaan.
   Format maklumat asas ialah: *kunci* medan penerangan (*kunci* Ayat huraian)
   Format parameter dan pembolehubah ialah: *kunci* ~*jenis*~ medan penerangan (*kunci* ~*jenis*~ Ayat deskriptif)
   Nota: *Kata kunci* dan ~*Jenis*~ boleh dinyatakan menggunakan mana-mana huruf dan nombor.
   Salin kod Kod adalah seperti berikut:
   
   fungsi (foo, bar) {
   // foo: Rentetan
   // digunakan untuk menjadi parameter pertama
   // bar: int
   // digunakan untuk menjadi parameter kedua
   }
   

   Pembolehubah

   Memandangkan pengisytiharan pembolehubah contoh, pembolehubah prototaip dan pembolehubah luaran adalah konsisten, terdapat banyak cara untuk mengisytiharkan dan mengubah suai pembolehubah. Takrifan dan kedudukan khusus hendaklah menunjukkan nama, jenis, skop dan maklumat lain bagi pembolehubah di tempat ia mula-mula muncul.

   Salin kod Kod adalah seperti berikut:
   
   fungsi foo() {
   // myString: String
   // kali: int
   // Berapa kali untuk mencetak myString
   // pemisah: Rentetan
   // Perkara yang hendak dicetak di antara myString*
   this.myString = "teks pemegang tempat";
   this.times = 5;
   }
   foo.prototype.setString = fungsi (myString) {
   this.myString = myString;
   }
   foo.prototype.toString = function() {
   untuk(int i = 0; i < this.times; i ) {
   dojo.debug(this.myString);
   dojo.debug(foo.separator);
   }
   }
   foo.separator = "=====";
   

   Anotasi pembolehubah dalam objek

   hendaklah ditanda dengan cara yang sama seperti nilai objek dan kaedah, contohnya apabila ia diisytiharkan:

   Salin kod Kod adalah seperti berikut:
   
   {
   // kunci: Rentetan
   // Nilai mudah
   kunci: "nilai",
   // kekunci2: Rentetan
   // Satu lagi nilai mudah
   }
   

   Nilai pulangan

   Oleh kerana fungsi boleh mengembalikan berbilang nilai (jenis) berbeza pada masa yang sama, ulasan jenis pulangan harus ditambah selepas setiap nilai pulangan. Komen boleh dibuat dalam baris Jika semua nilai pulangan adalah daripada jenis yang sama, nyatakan jenis pulangan yang berbeza, tandakan jenis pulangan sebagai "bercampur".

   Salin kod Kod adalah seperti berikut:
   
   function() {
   if (arguments.length) {
   return „Sie haben Argument(e) übergeben“; // String
   } sonst {
   return false; // Boolean
   }
   }
   

   Pseudocode (zu besprechen)

   Manchmal müssen Sie der Funktion oder Klasse eine funktionale Prozessbeschreibung der Funktion oder Klasse hinzufügen. Wenn Sie dies planen, können Sie /*======== verwenden (= das Zeichen kommt vorzugsweise 5 Mal oder öfter vor), was den Vorteil hat, dass diese Dinge nicht zum Code hinzugefügt werden müssen (Anmerkung: Ursprünglicher Autor Es kann sich um ein Code-Management-System handeln.

   Es sieht so aus, als ob in /*====== und =====*/ ein sehr langer Kommentar vorhanden sein wird. Sie können überlegen, ob Sie ihn löschen möchten, nachdem die Funktionsanpassung abgeschlossen ist.
   

   Code kopieren Der Code lautet wie folgt:
   
   /*=====
   module.pseudo.kwArgs = {
   // URL: String
   // Der Speicherort der Datei
   URL: "",
   // mimeType: String
   // Text/HTML, Text/XML usw.
   mimeType: ""
   }
   =====*/

   function(/*module.pseudo.kwArgs*/ kwArgs){
   dojo.debug(kwArgs.url);
   dojo.debug(kwArgs.mimeType);
   }
   

   Originallink: http://dojotoolkit.org/developer/StyleGuide
   Übersetzt von: i.feelinglucky{at}gmail.com von http://www.gracecode.com