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

ทำตามคู่มือสไตล์ Google TypeScript

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

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

ควรทำ

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

ไม่ควรทำ

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

เอกสารการแก้ปัญหา

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

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

ประเภท

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

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

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

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

เอกสาร TSS สำหรับพร็อพเพอร์ตี้ควรมีคำอธิบายพร็อพเพอร์ตี้ รายละเอียดที่พักที่ชี้แจงได้ก็อาจไม่แสดง

/**
  *   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;
}