此頁內容來自 JSHint 專案儲存庫。如果您發現錯誤，請 開啟問題回報，或（更好）提出拉取要求！

如何參與

針對專案的貢獻通常分為三種形式

  • 錯誤回報
  • 功能要求
  • 修補程式

本文件說明針對各類回報及要求的最佳貢獻方式。維護團隊將指派下列標籤之一，說明回報的嚴重程度

  • P1： 某些程式碼會擲回例外狀況；破壞 JSHint 向下相容性。
  • P2： 某些程式碼無法正確剖析。
  • P3：核心團隊將在完成 P2 和 P1 後著手處理的功能。
  • P4：歡迎修補程式；請求內容良好，但優先順序較低。

錯誤回報

如果您相信已發現不當的行為，請透過提交問題回報，讓團隊知悉。為幫助團隊診斷並修正問題，問題回報應包含下列資訊

  • 所使用的 JSHint 版本
  • 輸入原始碼（簡化成僅包含示範問題所需細節）
  • 設定值
  • 預期行為說明
  • 實際行為說明

請避免使用截圖示範問題。使用純文字說明您的問題（並在適當情況下使用「code」中繼標記格式），這樣可以讓更多人更容易閱讀您的回報，也能讓搜尋引擎更容易搜尋到。

功能要求

如果您想到一些可以改善 JSHint 的新功能，我們很樂意聽聽！優秀的功能要求應包含下列資訊

  • 功能解決的問題說明
  • 功能預期運作的大綱
  • 任何特例/例外情況清單，以及其應如何處理

如果您具備實作該功能及提交修補程式的能力，那就更好了！請先提出功能要求，以便維護人員驗證要求是否得宜，並協助調整設計。

修補程式

提交修補程式是確保您的問題獲得處理的最佳方式。我們接受透過所有媒介提供的修補程式：拉取要求、電子郵件、問題留言、附有程式碼片段連結的推文等。

不過，在傳送修補程式之前，請確定符合下列各項

  • 您的提交訊息符合 提交訊息指南。
  • 您的修補程式沒有無用的合併提交。
  • 您的編碼風格與我們類似（請見下方說明）。
  • 您的修補程式經過 100% tested 測試。我們不接受任何測試回歸。
  • 所有測試和提示檢查均通過（npm test）。
  • 您了解我們非常感謝您的修補程式。

開發環境

JSHint 使用 Node.js 進行開發，並在 package.json 檔案中指定多項相依性。要安裝這些相依性，您只需從 repo 目錄中執行下列命令

$ npm install

執行後，您將可以使用 bin/jshint 執行 JSHint 邊緣版本，或使用 bin/build 建立發行套件。

編碼風格

本節說明我們的編碼風格指南。您可能不同意，但如果您要傳送修補程式給我們，請將此指南視為法律。

我們的首要規則非常簡單

任何碼庫中的所有程式碼都應看起來像單獨一個人編寫的，不論有多少人參與貢獻。—idiomatic.js

空白

  • 我們在所有地方都使用兩個空白。
  • 在 if、for、while 等之後留一個空格。

  • 對於匿名函式，function 與 ( 之間不得留空格；對於有名稱的函式，名稱與 ( 之間不得留空格。

    var a = function() {};
function a() {}

  • 若能讓程式碼更加美觀，請隨時縮排變數分配或屬性定義。但不得過度使用。

    // Good
var next = token.peak();
var prev = token.peak(-1);
var cur  = token.current;

var scope = {
  name:   "(global)",
  parent: parentScope,
  vars:   [],
  uses:   []
};

// Bad
var cur         = token.current;
var isSemicolon = cur.isPunctuator(";");

  • 多行註解的兩側要另起新行。

變數

  • 除非變數未指派任何值（且其長度夠短），否則每一個變數都使用一個 var

    var token = tokens.find(index);
var scope = scopes.current;
var next, prev, cur;

  • 變數名稱不需過於詳盡，但也不可過度簡潔而僅使用一個字母。找出一個恰當的平衡點。

註解

  • 針對所有不明顯的部分加上註解。
  • 如果新增檢查項目，請撰寫註解，說明該檢查項目的重要性及檢查內容。

其他

  • 務必使用嚴格模式。
  • 務必使用嚴格比較：=== 和 !==。
  • 使用分號。
  • 請勿使用逗號優先記法。
  • 嘗試不要串聯多個項目，除非這麼做有助於程式碼（例如在測試中）。

  • 如果不指派結果，請勿使用短路運算式。

    // Good
token = token || tokens.find(0);

// Bad
token.isPunctuator(";") && report.addWarning("W001");

// Good
if (token.isPunctuator(";"))
  report.addWarning("W001");

提交訊息指南

提交訊息撰寫格式簡單，明確說明變更目的。

一般而言，格式應如下所示

[[TYPE]] <Short description>
<Blank line>

<Body / Detailed description>

<Footer>

提交訊息的行長沒有嚴格限制，但理想的提交訊息主旨不超過 60 個字元，內文及註腳在第 100 個字元處折行。此格式於 Github 的 UI 呈現最佳效果。

主旨

第一行是提交訊息的主旨，其中會指出變更類型和該變更的一般說明。理想狀況下，主旨長度應在 60 個字元內。例如

[[FIX]] Ignore "nocomma" when parsing object literals

標題 [[FIX]] 指出該變更為錯誤修正，而後面的內容說明該變更的實際內容。

jshint 使用多種提交類型

  1. [[FIX]] --- 提交修正錯誤或回歸問題
  2. [[FEAT]] --- 提交引進新功能
  3. [[DOCS]] --- 提交修改文件。文件提交僅應針對原始碼中的註解或用於產生文件說明的腳本及資產進行調整。
  4. [[TEST]] --- 提交僅修改測試或測試架構
  5. [[CHORE]] --- 提交影響開發作業、持續整合或套件依賴項目的內容

內文

<Body> 是詳細的提交訊息，說明確切變更內容，並概述變更原因。內文各行應折行在第 100 個字元處，以利最佳呈現。

歷史範例，請參閱此 範例

註腳

<Footer> 包含對所有重大變更的說明，無論多麼細微，以及受此提交影響或修正的問題清單。註腳各行應折行在第 100 個字元處，以利最佳呈現。

例如

[[FEAT]] Enable `norecurs` option by default

Commit 124124a7f introduced an option which forbids recursion. We liked it so much, we've enabled
it by default.

BREAKING CHANGE:

This change will break the CI builds of many applications and frameworks.

In order to work around this issue, you will need to re-engineer your applications and frameworks
to avoid making recursive calls. Use Arrays as stacks rather than relying on the VM call stack.

Fixes #1000009
Closes #888888
Closes #77777