Skip to content

Latest commit

 

History

History
727 lines (505 loc) · 35 KB

README-id.md

File metadata and controls

727 lines (505 loc) · 35 KB
Raw

Standard - JavaScript Style Guide
JavaScript Standard Style

discord travis npm version npm downloads Standard - JavaScript Style Guide

Sponsored by    Speakeasy

English • Español (Latinoamérica) • Français • Bahasa Indonesia • Italiano (Italian) • 日本語 (Japanese) • 한국어 (Korean) • Português (Brasil) • 简体中文 (Simplified Chinese) • 繁體中文 (Taiwanese Mandarin)

Panduan penulisan Javascript, linter, dan formatter

Modul ini menghemat waktu kamu (dan lainnya!) dengan tiga cara:

  • Tanpa konfigurasi. Cara paling mudah untuk menaikan kualitas kode kamu didalam projek. Tanpa harus membuat keputusan. Tanpa berkas.eslintrc untuk dikelola. Tinggal dijalankan.
  • Secara otomatis memformat kode. Tinggal jalankan standard --fix dan katakan selamat tinggal pada kode yang berantakan dan tidak konsisten.
  • Tangkap masalah gaya penulisan & error dari programmer dengan cepat. Hemat waktu untuk mereview kode dengan mengeliminasi kegiatan bolak-balik antara reviewer & kontributor.

Cobalah dengan menjalankan npx standard --fix sekarang juga!

Daftar isi

Pemasangan

Cara paling mudah untuk menggunakan Javascript Standard Style adalah dengan menginstallnya secara global dengan program Node line command. Jalankan perintah berikut didalam Terminal:

$ npm install standard --global

Atau, kamu bisa memasang standard secara lokal, untuk penggunaan didalam projek tunggal:

$ npm install standard --save-dev

Catatan: Untuk menjalankan perintah-perintahnya, Node.js dan npm harus diinstall terlebih dahulu.

Penggunaan

Setelah kamu memasang standard, kamu harusnya sudah bisa untuk menggunakan program standard. Kasus paling sederhananya adalah memeriksa gaya penulisan dari seluruh berkas Javascript didalam direktori yang sedang digunakan:

$ standard
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.

Jika kamu memasang standard secara lokal, lebih baik jalankan dengan npx:

$ npx standard

Secara opsional kamu bisa memberikan sebuah direktori (atau direktori-direktori) menggunakan pola glob. Pastikan kamu memberikan tanda kutip pada path yang menganduk pola glob jadi direktori-direktorinya diperluas oleh standard daripada oleh shell-nya:

$ standard "src/util/**/*.js" "test/**/*.js"

Note: secara default standard akan mencari seluruh berkas berkas dengan pola yang sama: **/*.js, **/*.jsx.

Apa yang kamu lakukan jika kamu pintar

  1. Tambahkan kedalam package.json
{
  "name": "my-cool-package",
  "devDependencies": {
    "standard": "*"
  },
  "scripts": {
    "test": "standard && node my-tests.js"
  }
}
  1. Gaya diperiksa secara otomatis ketika kamu menjalankan npm test
$ npm test
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.
  1. Tidak perlu memberikan feedback pada gaya penulisan didalam pull request lagi!

Kenapa saya harus menggunakan Javascript Standard Style?

Keindahan dari Javascript Standard Style adalah kesederhanannya. Tidak ada seorangpun yang ingin memelihara berkas dengan ratusan-baris gaya konfigurasi untuk setiap modul/projek yang dikerjakan. Cukup untuk kegilaan itu!

Modul ini menghemat waktu kamu (dan lainnya!) dengan tiga cara:

  • Tanpa konfigurasi. Cara paling mudah untuk menaikan kualitas kode kamu didalam projek. Tanpa harus membuat keputusan. Tanpa berkas.eslintrc untuk dikelola. Tinggal masukan.
  • Secara otomatis memformat kode. Tinggal jalankan standard --fix dan katakan selamat tinggal pada kode yang berantakan dan tidak konsisten.
  • Tangkap masalah gaya penulisan & error dari programmer dengan cepat. Hemat waktu untuk mereview kode dengan mengeliminasi kegiatan bolak-balik antara reviewer & kontributor.

Mengadopsi gaya standard berarti meninggikan pentingnya kejelasan dan konvensi komunitas lebih tinggi daripada gaya penulisan sendiri. Hal ini mungkin tidak masuk akal untuk 100% projek dan kultur dari pengembangan, entah bagaimana untuk open source bisa menjadi tempat yang dihindari oleh pemula. Siapkan dengan jelas, ekspektasi otomasi kontributor membuat projek lebih baik.

Untuk info lebih, lihatlah obrolan konferensi "Write Perfect Code with Standard and ESLint". Didalam obrolan ini, kamu akan belajar tentang linting, kapan ketika menggunakan standard dibandingkan dengan eslint, dan bagaimana indahnya dibandingkan dengan standard.

Siapa yang menggunakan Javascript Standard Style?
Free MIDIs, MIDI file downloads College essays, AP notes
Your logo here Your logo here Your logo here

Selain perusahaan, beberapa anggota komunitas menggunakan standard didalam packages yang terlalu banyak untuk ditampilkan disini.

standard juga merupakan linter dengan peringkat teratas didalam showcase Github Clean Code Linter.

Apakah terdapat plugin untuk text editor?

Pertama, pasang standard. Lalu, pasang plugin yang sesuai untuk editor kamu:

Sublime Text

Menggunakan Package Control, pasang SublimeLinter dan SublimeLinter-contrib-standard.

Untuk formating otomatis saat menyimpan, pasang StandardFormat.

Atom

Pasang linter-js-standard.

Secara alternatif, kamu bisa memasang linter-js-standard-engine. Daripada versi standard yang telah digabungkan, versi ini akan secara otomatis menggunakan versi yang telah terpasang didalam projek yang sedang digunakan. Versi ini juga akan bekerja dengan linter lainnya yang berdasarkan standard-engine.

Untuk formating otomatis, pasang standard-formatter. Untuk snippets, pasang standardjs-snippets.

Visual Studio Code

Pasang vscode-standard. (Sudah termasuk dukungan untuk pem-format otomatis.)

Snippets untuk JS, pasang vscode-standardjs-snippets. Snippets untuk React, pasang vscode-react-standard.

Vim

Pasang ale. Dan tambahkan baris ini kedalam berkas .vimrc.

let g:ale_linters = {
\   'javascript': ['standard'],
\}
let g:ale_fixers = {'javascript': ['standard']}

Kode ini akan menyetel standard sebagai satu-satunya linter dan fixer untuk file javascript kamu dan menghindari konflik dengan eslint. Untuk linting dan pembenaran otomatis saat disimpan, tambahkan baris ini kedalam .vimrc:

let g:ale_lint_on_save = 1
let g:ale_fix_on_save = 1

Plugin alternatif untuk dipertimbangkan neomake dan syntastic, keduanya memiliki dukungan bawaan untuk standard (walaupun konfigurasi mungkin masih dibutuhkan).

Emacs

Pasang Flycheck dan lihat manual untuk mempelajari bagaimana cara menggunakannya didalam projek kamu.

Brackets

Carilah ekstensi registry untuk "Standard Code Style" dan klik "Install".

WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains, etc.)

WebStorm baru saja mengumumkan dukungan natif untuk standard langsung didalam IDE.

Jika kamu lebih suka untuk mengkonfigurasi standard secara manual, ikuti arahan disini. Arahan tersebuh dapat diaplikasikan kedalam seluruh produk JetBrains, termasuk PhpStorm, IntelliJ, RubyMine, etc.

Apakah terdapat badge readme?

Ya! jika kamu menggunakan `standard didalam projek kamu, kamu bisa memasukan salah satu dari badge ini didalam readme kamu untuk membiarkan orang-orang tahu bahwa kode kamu menggunakan gaya standard.

JavaScript Style Guide

[![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)

JavaScript Style Guide

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

Saya tidak setuju dengan aturan X, bisakah diganti??

Tidak. Point utama dari standard adalah untuk menghemat waktu kamu dengan menghindari bikeshedding didalam gaya penulisan. Masih banyak perdebatan obline tentang penggunaan tabs dengan spasi, dll. Yang mana tidak akan berakhir. Debat-debat ini hanya akan mengganggu kita menyelesaikan pekerjaan kita. Pada akhirnya kamu 'harus memilih sesuatu', dan itulah seluruh filosofi dari standard -- 'pilihlah sesuatu' adalah opini yang masuk akal. Semoga, pengguna melihat nilai dari opini itu daripada harus terus berdebat tentang hal-hal lainnya.

Terdapat beberapa package yang mirip untuk orang-orang yang tidak ingin sepenuhnya menggunakan standard:

Jika kamu benar-benar ingin mengkonfigurasi ratusan dari aturan ESLint satu persatu, kamu selalu bisa menggunakan eslint langsung dengan eslint-config-standard untuk melapisi perubahan terlebih dahulu. standard-eject bisa membantu kamu memigrasi dari standard menjadi eslint dan eslint-config-standard.

Saran ahli: Gunakanlah standard. Terdapat masalah sesungguhnya yang mana akan menghabiskan waktu kamu dalam memecahkan masalahnya! :P

Tapi ini bukanlah standar web yang sesungguhnya!

Tentu saja bukan! Gayanya yang digunakan disini tidak terdapat pada official web standards groups manapun, itulah kenapa repo ini dipanggil dengan standard/standard dan bukan ECMA/standard.

Kata dari "standard" memiliki arti lebih dari "web standard" :-) Contoh:

  • Modul ini membantu kode kita untuk memiliki kualitas dari standard yang tinggi.
  • Modul ini memastikan bahwa kontributor baru mengikuti dasar dari beberapa style standards.

Apakah terdapat formater yang otomatis?

Ya! Kamu bisa menggunakan standard --fix untuk memperbaiki kebanyakan masalah secara otomatis.

standard --fix dibuat kedalam standard untuk kenyamanan yang maksimal. Tapi kebanyakan masalah dapat diperbaiki, tapi beberapa error (seperti lupa untuk menghandle error) harus diperbaiki secara manual.

Untuk menghemat waktu kamu, standard mengeluarkan pesan "Run standard --fix untuk secara otomatis memperbaiki beberapa masalah" ketika kode tersebut mendeteksi masalah yang bisa diperbaiki secara otomatis.

Bagaimana cara saya mengabaikan berkas?

Beberapa path (node_modules/, coverage/, vendor/, *.min.js, dan berkas/folder yang dimulai dengan . seperti .git/) akan secara otomatis diabaikan.

Path didalam sebuah file projek root .gitignore juga secara otomatis diabaikan.

Terkadang kamu perlu untuk mengabaikan folder tambahan atau file tertentu yang telah di minified. Untuk melakukan hal itu, tambahkan properti standard.ignore didalam package.json:

"standard": {
  "ignore": [
    "**/out/",
    "/lib/select2/",
    "/lib/ckeditor/",
    "tmp.js"
  ]
}

Bagaimana cara menyembunyikan peringatan tertentu?

Didalam kasus yang jarang terjadi, kamu perlu keluar dari aturan dan menyembunyikan peringatan yang dibuat oleh standard.

Javascript Standard Style menggunakan ESLint didalamnya dan kamu bisa menyembunyikan peringatan seperti saat kamu menggunakan ESLint secara langsung.

Untuk mendapatkan output yang bertele-tele (jadi kamu bisa menemukan nama aturan untuk diabaikan), jalankan:

$ standard --verbose
Error: Use JavaScript Standard Style
  routes/error.js:20:36: 'file' was used before it was defined. (no-use-before-define)

Nonaktifkan semua aturan didalam baris tertentu:

file = 'I know what I am doing' // eslint-disable-line

Atau, Nonaktifkan hanya aturan"no-use-before-define":

file = 'I know what I am doing' // eslint-disable-line no-use-before-define

Atau, nonaktifkan aturan "no-use-before-define" untuk beberapa baris:

/* eslint-disable no-use-before-define */
console.log('offending code goes here...')
console.log('offending code goes here...')
console.log('offending code goes here...')
/* eslint-enable no-use-before-define */

Saya menggunakan librari yang memenuhi penamaan global. Bagaimana cara saya menghindari error "variable is not defined"?

Beberapa package (seperti mocha) yang memasukan fungsinya (seperti describe, it) didalam objek global (bentuk yang buruk). Sejak fungsi-fungsi ini tidak didefinisikan atau require dimanapun didalam kode kamu, standard akan memperingatkan bahwa kamu menggunakan variabel yang tidak didefinisikan (biasanya, aturan ini akan sangat berguna untuk menangkap typo-typo!). Tapi kita ingin menonaktifkannya untuk variabel-variabel global.

Untuk membiarkan standard (tentunya sama seperti manusia yang membaca kode kamu) mengetahui bahwa beberapa variabel adalah global didalam kode kamu, tambahkan ini dipaling atas dari berkas kamu:

/* global myVar1, myVar2 */

Jika kamu mempunyai ratusan berkas, mungkin kamu ingin menghindari menambahkan komentar disetiap berkas. Dalam kasus ini, jalankan:

$ standard --global myVar1 --global myVar2

Atau, tambahkan ini kedalam package.json:

{
  "standard": {
    "globals": [ "myVar1", "myVar2" ]
  }
}

Catatan: global dan globals sama saja.

Bagaimana cara saya menggunakan fitur javascript yang experimental (ES Next)?

standard mendukung fitur ECMAScript yang paling terbaru, ES8 (ES2017), termasuk fitur proposal bahasa yang mana sekarang didalam "Stage 4" dari proses proposal.

Untuk mendukun fitur bahasa eksperimental, standard menspesifikasikan dukungan kustom parser Javascript. Sebelum menggunakan parser kustom, pertimbangkan apakah menambahkan kompleksitas akan bermanfaat.

Untuk mendukung parser kustom, pertama pasang dahulu dari npm:

npm install @babel/eslint-parser --save-dev

Lalu jalankan:

$ standard --parser @babel/eslint-parser

Atau, tambahkan ini kedalam package.json:

{
  "standard": {
    "parser": "@babel/eslint-parser"
  }
}

Bisakah saya menggunakan varian bahasa Javascript, seperti Flow atau Typescript?

standard mendukung fitur ECMAScript yang paling terbaru. Namun, Flow dan TypeScript menambahkan sintaks baru kedalam bahasanya, jadi keduanya tidak didukung.

Untuk mendukung varian bahasa dari Javascript, standard mendukung menspesifikasikan parser Javascript kustom sama sepertin plugin ESLint untuk meng-handle perubahan sintaks. Sebelum menggunakan varian bahasa dari Javascript, pertimbangkan apakah menambah kompleksitas akan bermanfaat.

Flow

Untuk menggunakan Flow, kamu harus menjalankan standard dengan @babel/eslint-parser sebagai parsernya dan eslint-plugin-flowtype sebagai pluginnya.

npm install @babel/eslint-parser eslint-plugin-flowtype --save-dev

Lalu jalankan:

$ standard --parser @babel/eslint-parser --plugin flowtype

Atau, tambahkan ini kedalam package.json:

{
  "standard": {
    "parser": "@babel/eslint-parser",
    "plugins": [ "flowtype" ]
  }
}

Catatan: plugin dan plugins sama saja.

TypeScript

Untuk menggunakan TypeScript, kamu harus menjalankan standard dengan @typescript-eslint/parser sebagai parsernya, @typescript-eslint/eslint-plugin sebagai pluginnya, dan beritahu standard untuk lint berkas **/*.ts (karena hal itu tidak diimplementasikan secara default).

Sayangnya, terdapat masalah yang terjadi diluar dugaan dengan standard dan TypeScript dimana standard mengeluarkan error unused-variable yang tidak benar (misal: ketika kamu mengimport interface). Dan sebagai solusi, kamu bisa menggunakan standardx 😅.

npm install standardx @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

Lalu jalankan:

$ standardx --parser @typescript-eslint/parser --plugin @typescript-eslint/eslint-plugin **/*.ts

Atau, tambahkan ini kedalam package.json:

{
  "eslintConfig": {
    "rules": {
      "no-unused-vars": "off",
      "@typescript-eslint/no-unused-vars": "error"
    }
  },
  "standardx": {
    "parser": "@typescript-eslint/parser",
    "plugins": [ "@typescript-eslint/eslint-plugin" ]
  }
}

Dengan kode diatas didalam package.json, kamu bisa menjalankan:

standardx **/*.ts

Dan kamu mungkin harus menghilangkan standard juga untuk menghindari kebingungan dimana itu digunakan secara tidak sengaja dimana seharusnya standarx.

npm uninstall standard

Bagaimana dengan Mocha, Jest, Jasmine, QUnit, etc?

Untuk dukungan mocha didalam berkas test, tambahkan kode ini dibagian paling atas dari berkas test:

/* eslint-env mocha */

Atau, Jalankan:

$ standard --env mocha

Dimana mocha bisa jadi salah satu dari jest, jasmine, qunit, phantomjs, dan lainnya. Untuk melihat seluruh daftar, lihat dokumentasi ESLint specifying environments. Untuk melihat global apa saja yang tersedia didalam environment ini, lihat npm modul globals.

Catatan: env dan envs sama saja.

Bagaimana dengan Web Workers dan Service Workers?

Tambahkan kode ini dibagian paling atas dari berkas web worker:

/* eslint-env worker */

Kode diatas membiarkan standard (sama seperti manusia yang membaca kodenya) tahu bahwa self adalah sebuah global didalam kode web worker.

Untuk Service Worker, tambahkan kode ini:

/* eslint-env serviceworker */

Bisakah saya memeriksa kode didalam berkas Markdown atau HTML?

Untuk memeriksa berkas Markdown, gunakan standard-markdown.

Alternatifnya, terdapat plugin ESLint yang bisa memeriksa kode didalam Markdown, HTML, dan berkas dengan bahasa yang lain:

Untuk memeriksa kode didalam berkas Markdown, gunakan plugin ESLint:

$ npm install eslint-plugin-markdown

Lalu, untuk memeriksa JS yang muncul didalam blok kode, jalankan:

$ standard --plugin markdown '**/*.md'

Untuk memeriksa kode didalam berkas HTML, gunakan plugin ESLint:

$ npm install eslint-plugin-html

Lalu, untuk memeriksa JS yang muncul didalam tag <script>, jalankan:

$ standard --plugin html '**/*.html'

Apakah terdapat Git pre-commit hook?

Lucu sekali ketika kamu bertanya hal ini!

#!/bin/bash

# Memastikan seluruh berkas javascript siap untuk dicommit dengan gaya penulisan standard
function xargs-r() {
  # Versi portable dari "xargs -r". Tanda -r adalah ekstensi GNU yang
  # menghindari xargs untuk berjalan jika tidak ada berkas yang dimasukan.
  if IFS= read -r -d $'\n' path; then
    echo "$path" | cat - | xargs "$@"
  fi
}
git diff --name-only --cached --relative | grep '\.jsx\?$' | sed 's/[^[:alnum:]]/\\&/g' | xargs-r -E '' -t standard
if [[ $? -ne 0 ]]; then
  echo 'JavaScript Standard Style errors were detected. Aborting commit.'
  exit 1
fi

Bagaimana cara membuat outputnya menjadi berwarna dan cantik?

Output bawaannya sangat sederhana dan jelas, tapi jika kamu suka sesuatu yang indah, pasang snazzy:

$ npm install snazzy

Dan jalankan:

$ standard --verbose | snazzy

Juga ada standard-tap, standard-json, standard-reporter, dan standard-summary.

Apakah terdapat API untuk Node.js?

Ya!

standard.lintText(text, [opts], callback)

Lint sumber text yang disediakan. Objek opts bisa juga disediakan:

{
  cwd: '',      // direktori yang sedang digunakan (default: process.cwd())
  filename: '', // path dari berkas yang mengandung text yang sedang di lint (opsional, walaupun didalam beberapa plugin eslint harus ada)
  fix: false,   // secara otomatis memperbaiki masalah
  globals: [],  // variabel global kustom untuk dideklarasikan
  plugins: [],  // plugin eslint kustom
  envs: [],     // environment kustom eslint
  parser: ''    // parser js kustom (e.g. @babel/eslint-parser)
}

Option tambahan mungkin di ambil dari package.json jika ditemukan didalam direktori yang sedang digunakan.

callback akan dipanggil dengan sebuah objek Error dan results.

Objek results akan mengandung properti berikut:

var results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0,
      output: '' // source kode tetap (hanya ada dengan option {fix: true})
    }
  ],
  errorCount: 0,
  warningCount: 0
}

results = standard.lintTextSync(text, [opts])

Versi singkronus dari standard.lintText(). Jika sebuah error muncul, sebuah exception akan dikeluarkan. Sebaliknya, sebuah objek results akan dikembalikan.

standard.lintFiles(files, [opts], callback)

Lint globs files yang disediakan. Sebuah objek opts bisa disediakan:

var opts = {
  ignore: [],   // berkas globs untuk diabaikan (memiliki nilai default)
  cwd: '',      // direktori yang sedang digunakan (default: process.cwd())
  fix: false,   // secara otomatis memperbaiki kesalahan
  globals: [],  // variabel global untuk dideklarasikan
  plugins: [],  // plugin eslint
  envs: [],     // environment eslint
  parser: ''    // parser js (e.g. @babel/eslint-parser)
}

callbacknya akan dipanggil dengan sebuah objek Error dan results (sama seperti diatas).

Bagaimana caranya saya berkonstribusi kepada StandardJS?

Kontribusi sangat disambut! Lihat issues atau PRsnya, dan buatlah pull request jika kamu melihat ada kekurangan.

Ingin bertanya? Bergabunglah dengan kontributor didalam channel #standard IRC di freenode.

Ini adalah beberapa package penting didalam ekosistem standard:

Juga terdapat beberapa plugin editor, daftar dari package npm yang digunakan standard, dan daftar yang bagus dari package didalam ekosistem standard.

Kebijakan dan Prosedur Keamanan

Tim dari standard dan komunitas memeriksa seluruh bug didalam standard dengan serius. Periksa dokumen kebijakan dan prosedur keamanan untuk belajar bagaimana cara melaporkan masalah.

Lisensi

MIT. Copyright (c) Feross Aboukhadijeh.