คู่มือแนะนำสไตล์ Blockly

ปฏิบัติตามคู่มือสไตล์ TypeScript ของ Google

การย้ายข้อมูลไปยัง TypeScript และ ES6

Blockly เขียนขึ้นครั้งแรกใน ES5.1 โดยสอดคล้องกับบุคคลเก่า ของรูปแบบ Google JavaScript เวอร์ชันปัจจุบัน เขียนใหม่ ควรเป็นไปตามคู่มือรูปแบบปัจจุบันและใช้ฟีเจอร์ภาษา ES6 เช่น let, const, class โดยทำลายการมอบหมายนี้ (หากมี) รหัสที่มีอยู่อาจได้รับการอัปเดตหรือไม่ได้รับการปฏิบัติตามข้อกำหนด ทีม Blockly พยายามที่จะตัดสินใจอย่างดีที่สุดโดยคำนึงถึงความสอดคล้องของโค้ดและ ประสบการณ์ของผู้ใช้ไลบรารี - ตัวอย่างเช่น เราอาจเลือกที่จะไม่เปลี่ยนชื่อ ฟังก์ชันสาธารณะที่ไม่เป็นไปตามคู่มือรูปแบบ

ควรทำ

• ใช้เครื่องมือวิเคราะห์โค้ดและการจัดรูปแบบ
  • เราใช้ eslint และมีการตั้งค่า.eslintrc.js ไฟล์ขึ้นโดยมีกฎสำหรับสไตล์ที่ต้องการ
  • เราใช้ prettier เพื่อการจัดรูปแบบอัตโนมัติ
  • เรียกใช้ npm run lint เพื่อเรียกใช้โปรแกรมวิเคราะห์โค้ดและ npm run format เพื่อเรียกใช้ ตัวจัดรูปแบบ
• เยื้องด้วยการเว้นวรรค ไม่ใช่แท็บ
• ใช้เซมิโคลอน
• ใช้ camelCase สําหรับตัวแปรและฟังก์ชัน
• ใช้ TitleCase สำหรับชั้นเรียน
• ใช้ ALL_CAPS สำหรับค่าคงที่
• ใช้วงเล็บปีกกา สำหรับโครงสร้างการควบคุมทั้งหมด
  • ข้อยกเว้น: คุณละเว้นวงเล็บสำหรับคำสั่ง if แบบบรรทัดเดียวได้
• ใช้เครื่องหมายคำพูดเดี่ยว (ยกเว้นเมื่อเขียน JSON)
• ประกาศตัวแปรใหม่ในวง for กล่าวคือ ให้เขียน for (const i = 0; ...) แทน for (i = 0; ...) เสมอ
  • หากไม่ทำเช่นนั้น เพิ่มความเสี่ยงที่ว่าหลังจากการเปลี่ยนโครงสร้างภายในโค้ด ตัวแปรจะกลายเป็นรายการที่ไม่มีที่มาและกลายเป็นสิ่งที่น่าประหลาดใจทั่วโลก
• ขึ้นต้นความคิดเห็นด้วยอักษรตัวพิมพ์ใหญ่และลงท้ายด้วยเครื่องหมายจุด
• สร้างปัญหาเกี่ยวกับ GitHub ด้วยสิ่งที่ต้องทำ แล้วลิงก์ปัญหาโดยใช้ TODO(#issueNumber)
• ใส่คำอธิบายประกอบทุกอย่างด้วย TSDoc

ไม่ควรทำ

• เยื้องด้วยแท็บ
• ใช้ขีดล่างที่ส่วนท้ายของชื่อตัวแปรหรือฟังก์ชัน
  • โค้ดก่อนหน้านี้บางโค้ดใช้ขีดล่างสำหรับพร็อพเพอร์ตี้ส่วนตัวหรือภายใน หรือ แม้ว่าโค้ดเหล่านี้จะยังคงอยู่ แต่ไม่ควรเพิ่มโค้ดใหม่ตามรูปแบบนี้
• ใช้ snake_case
• ใช้เครื่องหมายคำพูดคู่ (ยกเว้นเมื่อเขียน JSON)
• ใช้ TSDoc ที่มีรูปแบบไม่ถูกต้อง
  • ระบบจะเผยแพร่ TSDoc ของเราโดยอัตโนมัติเป็นส่วนหนึ่งของเอกสารประกอบ
• เขียน TODO (username)
  • แต่ให้สร้างปัญหา GitHub ที่มี TODO แล้วลิงก์โดยใช้ TODO(#issueNumber)
• ใช้ string.startsWith โปรดใช้ Blockly.utils.string.startsWith แทน

TSDoc

ทีม Blockly ใช้ TSDoc เพื่อใส่คำอธิบายประกอบโค้ดและ สร้างเอกสารประกอบ เราคาดหวังให้ TSDoc มีไว้สำหรับทรัพย์สินสาธารณะทั้งหมดของชั้นเรียน และสำหรับฟังก์ชันที่ส่งออกทั้งหมด

ความคิดเห็นของ TSDoc ต้องขึ้นต้นด้วย /** และลงท้ายด้วย */ จึงจะได้รับการแยกวิเคราะห์อย่างถูกต้อง

ประเภท

ประเภทจะไม่แสดงใน TSDoc เนื่องจากข้อมูลดังกล่าวอยู่ในโค้ด TypeScript โดยตรง หากคุณแก้ไขไฟล์ JavaScript ที่เหลืออยู่เพียงไม่กี่ไฟล์ ให้ใส่คำอธิบายประกอบประเภทตามเอกสารประกอบของ Closure Compiler

ระดับการแชร์

ฟังก์ชันหรือพร็อพเพอร์ตี้ที่ควรเข้าถึงภายในไลบรารี Blockly เท่านั้น ควรใส่คำอธิบายประกอบด้วย @internal ซึ่งจะป้องกันไม่ให้พร็อพเพอร์ตี้เหล่านี้ปรากฏในเอกสารประกอบสาธารณะ ตัวปรับเปลี่ยนระดับการเข้าถึงอื่นๆ ควรวางไว้ในโค้ด TypeScript โดยตรง ไม่ใช่ใน TSDoc

พร็อพเพอร์ตี้

TSDoc สำหรับพร็อพเพอร์ตี้ควรมีคำอธิบายพร็อพเพอร์ตี้ อาจละเว้นคำอธิบายสำหรับพร็อพเพอร์ตี้ที่เข้าใจง่าย

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

ฟังก์ชัน

คําอธิบายประกอบสําหรับฟังก์ชันควรมี

• คำอธิบายฟังก์ชัน
• แท็ก @param 1 รายการต่อพารามิเตอร์ ซึ่งรวมถึง
  • ชื่อ
  • คำอธิบาย
• แท็ก @returns หากฟังก์ชัน จะแสดงผลค่า พร้อมด้วยคำอธิบายของค่าที่แสดงผล

คำอธิบายอาจละเว้นสำหรับฟังก์ชัน พารามิเตอร์ หรือค่าที่แสดงหาก ใช้ชื่อที่เข้าใจได้อยู่แล้ว

เช่น

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}