คู่มือแนะนํารูปแบบ

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

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

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

ควรทำ

• ใช้เครื่องมือการจัดรูปแบบและการตรวจหาข้อบกพร่อง
  • เราใช้ eslint และมีeslint.config.mjs ไฟล์ ที่ตั้งค่ากฎสำหรับสไตล์ที่ต้องการ
  • เราใช้ prettier เพื่อการจัดรูปแบบอัตโนมัติ
  • กด npm run lint เพื่อเรียกใช้โปรแกรมวิเคราะห์โค้ด และ npm run format เพื่อเรียกใช้โปรแกรมจัดรูปแบบ
• เยื้องด้วยเว้นวรรค ไม่ใช่แท็บ
• ใช้เซมิโคลอน
• ใช้ camelCase สำหรับตัวแปรและฟังก์ชัน
• ใช้ TitleCase สำหรับชั้นเรียน
• ใช้ ALL_CAPS สำหรับค่าคงที่
• ใช้วงเล็บสำหรับโครงสร้างการควบคุมทั้งหมด
  • ข้อยกเว้น: คุณละเว้นวงเล็บเหลี่ยมสำหรับคำสั่ง if แบบบรรทัดเดียวได้
• ใช้เครื่องหมายคำพูดเดี่ยว (ยกเว้นเมื่อเขียน JSON)
• ประกาศตัวแปรใหม่ในวง for กล่าวคือ ให้เขียน for (const i = 0; ...) แทน for (i = 0; ...) เสมอ
  • ไม่เช่นนั้น อาจมีความเสี่ยงที่หลังจากการแยกส่วนโค้ดที่สูงขึ้นในฟังก์ชันแล้ว ตัวแปรจะกลายเป็นตัวแปรส่วนกลางโดยไม่ได้ตั้งใจ
• ขึ้นต้นความคิดเห็นด้วยอักษรตัวพิมพ์ใหญ่และลงท้ายด้วยเครื่องหมายจุด
• สร้างปัญหา GitHub ที่มี TODO และลิงก์โดยใช้ 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;
}