Skip to main content
0
Software Development

Comment โค้ดอย่างไรให้ได้ประสิทธิภาพ

สำหรับการทำงานกับโค้ด โดยปกติแล้วไม่ใช่แค่เขียนออกมาให้ทำงานได้ แต่ยังต้องสามารถทำให้คนอื่นในทีม รวมถึงตัวเองในอนาคตสามารถอ่านแล้วเข้าใจ สามารถอัปเดตหรือแก้ไขโค้ดที่เคยเขียนเอาไว้ได้ การเขียน Comment ที่ดีจึงเป็นทักษะสำคัญที่จะช่วยให้โค้ดของเรามีคุณภาพและบำรุงรักษาได้ง่ายขึ้น

ทำไมต้องเขียน Comment ด้วย ?

การเขียน Comment ก็เหมือนการสร้างคู่มือ ที่คนเขียนโค้ดตอนแรกอาจจะไม่ได้ใช้ แต่ว่ามันมีประโยชน์แน่นอน (ถ้าเขียน Comment เอาไว้ดีอ่ะนะ) ลองดูตัวอย่างประโยชน์ที่เราได้จากการเขียน Comment

  1. สร้างความเข้าใจที่ชัดเจน
    • อธิบายแนวคิดและเหตุผลเบื้องหลังการเขียนโค้ด
    • ให้ context ที่จำเป็นสำหรับโค้ดที่ซับซ้อน
  2. เพิ่มประสิทธิภาพการทำงานร่วมกัน
    • ทีมสามารถเข้าใจและแก้ไขโค้ดของกันและกันได้ง่าย
    • ลดการสื่อสารที่ผิดพลาดระหว่างทีม
    • สร้างมาตรฐานในการพัฒนา
  3. สนับสนุนการบำรุงรักษาระยะยาว
    • บันทึกข้อควรระวังและข้อจำกัดต่างๆ
    • ช่วยในการ debug และแก้ไขบั๊ก
    • ลดเวลาในการทำความเข้าใจโค้ดเก่า

เขียน Comment แบบไหนได้บ้าง ?

ในแต่ละภาษาก็มี Syntax การเขียนที่ต่างกันออกไป แต่ว่าน่าจะแบ่งคร่าว ๆ ได้เป็น 3 แบบ คือ

1. Single Line Comments

Single Comments คือ Comment ที่จบในบรรทัดเดียวเขียนแทรกอยู่ในโค้ด เพื่ออธิบายส่วนที่ซับซ้อนหรือต้องการให้ข้อมูลเพิ่มเติม ในภาษา JavaScript เราจะใช้ // เป็นตัวเริ่มต้นการเขียน Comment ข้อความที่อยู่หลังจากเครื่องหมาย // ไปจนสิ้นสุดบรรทัดจะถูกนับว่าเป็น Comment ทั้งหมด ซึ่งสามารถเขียนไว้บรรทัดเดียวกันกับโค้ด หรือแยกบรรทัดกันก็ได้

// นี่คือคอมเมนต์แบบบรรทัดเดียว
let x = 5;

const y = 10 // นี่ก็แบบบรรทัดเดียวเหมือนกัน
JavaScript

2. Multiple Line Comment

ก็คือการเขียน Comment หลายบรรทัดตามชื่อ ซึ่งจริง ๆ แล้วเราสามารถเขียนแบบ Single Line หลายบรรทัดติดกันก็ได้ แต่ถ้าใช้ Syntax สำหรับเขียน Multiple Line ก็จะสะดวกกว่า เพราะใช้แค่การเขียน /* เป้นจุดเริ่มต้นและ */ เป็นจุดสิ้นสุดก็ใช้ได้แล้ว

/*
   นี่คือคอมเมนต์แบบหลายบรรทัด
   ใช้สำหรับอธิบายโค้ดยาวๆ
   หรือบันทึกข้อมูลเพิ่มเติม
*/
let a = 10;

// ส่วนแบบนี้ก็ได้เหมือนกัน
// แต่ว่าจะใช้งานไม่สะดวก
// อ่านยากกว่าด้วย
const b = 20
JavaScript

3. Documentation

อันที่จริงข้อนี้ไม่ได้เป็นการเขียน Comment โดยตรง แต่เป็นการเขียน Document ให้กับโค้ดของเรา โดยใช้รูปแบบการเขียนตามที่แต่ละภาษากำหนดมาตรฐานเอาไว้ อย่างใน JavaScript จะเรียกว่า JSDoc ซึ่งจะช่วยให้คนอื่นเข้าใจการทำงานของฟังก์ชัน, ตัวแปร, และคลาสต่าง ๆ ได้ง่ายขึ้น โดยการใช้คอมเมนต์แบบพิเศษ /** … */ ซึ่งมักจะมีแท็กที่อธิบายพารามิเตอร์ ผลลัพธ์ หรือคุณสมบัติต่าง ๆ ของโค้ด

/**
 * คำนวณผลรวมของจำนวนสองจำนวน
 *
 * @param {number} a - ตัวเลขตัวแรก
 * @param {number} b - ตัวเลขตัวที่สอง
 * @returns {number} ผลรวมของ a และ b
 */
function add(a, b) {
    return a + b;
}
JavaScript

เขียนยังไงให้มีประสิทธิภาพ ?

ขอแบ่งออกเป็น 3 กลุ่มกว้าง ๆ ตามนี้นะครับ

1. หลักการพื้นฐาน

1.1 Comment ควรสั้น กระชับ และมีความหมายชัดเจน

การเขียน Comment ที่ดีควรสั้น กระชับ และมีความหมายชัดเจน ใช้ภาษาที่เข้าใจง่าย ตรงประเด็น และให้ข้อมูลที่เป็นประโยชน์โดยไม่อธิบายสิ่งที่เห็นได้ชัดจากโค้ด วิธีนี้ช่วยให้ผู้อ่านเข้าใจจุดประสงค์ของโค้ดได้อย่างรวดเร็ว

// อัปเดตสถานะผู้ใช้ที่ไม่ได้เข้าสู่ระบบนานเกิน 30 วัน
function updateUserStatus(user) {
  const inactiveThreshold = 30 * 24 * 60 * 60 * 1000; // 30 วันในมิลลิวินาที
  if (Date.now() - user.lastLogin > inactiveThreshold) {
    user.status = 'inactive';
  }
}
JavaScript

1.2 ใช้ Comment เพื่ออธิบายเหตุผลของโค้ด

Comment ที่มีประสิทธิภาพควรอธิบายเหตุผลเบื้องหลังการเขียนโค้ด ไม่ใช่แค่บอกว่าโค้ดทำอะไร การให้ข้อมูลเกี่ยวกับการตัดสินใจในการเขียนโค้ดช่วยให้ผู้อ่านเข้าใจแนวคิดและเหตุผลของผู้เขียน ทำให้การบำรุงรักษาและแก้ไขโค้ดในอนาคตทำได้ง่ายขึ้น

// ใช้ throttle เพื่อจำกัดการเรียก API
// ป้องกันการโหลดข้อมูลมากเกินไปเมื่อผู้ใช้พิมพ์เร็ว
function throttledSearch(searchTerm) {
  clearTimeout(this.searchTimeout);
  this.searchTimeout = setTimeout(() => {
    this.performAPISearch(searchTerm);
  }, 300);
}
JavaScript

1.3 หลีกเลี่ยง Comment ที่ไม่จำเป็น

การเขียนโค้ดโดยจัดระเบียบและตั้งชื่อให้สื่อความหมายชัดเจน เป็นสิ่งที่ควรทำเสมอ ซึ่งในกรณีนี้เราไม่จำเป็นต้องใส่ Comment ซ้ำซ้อนเข้าไปอีก

function calculateDiscountedTotal(items, discountPercentage) {
  const subtotal = items.reduce((total, item) => total + item.price * item.quantity, 0);
  const discount = subtotal * (discountPercentage / 100);
  return subtotal - discount;
}
JavaScript

1.4 อัปเดต Comment เมื่อแก้ไขโค้ด การรักษา Comment ให้เป็นปัจจุบันเป็นสิ่งสำคัญเมื่อมีการแก้ไขโค้ด Comment ที่ไม่ตรงกับโค้ดปัจจุบันอาจทำให้เกิดความสับสนและข้อผิดพลาดในการพัฒนาได้

// ก่อนการแก้ไข:
// คำนวณภาษีมูลค่าเพิ่ม (VAT) 7% จากราคาสินค้า
function calculateVAT(price) {
  return price * 0.07;
}

// หลังการแก้ไข:
// คำนวณภาษีมูลค่าเพิ่ม (VAT) 7% และภาษีท้องถิ่น 3% จากราคาสินค้า
function calculateTax(price) {
  const vat = price * 0.07;
  const localTax = price * 0.03;
  return vat + localTax;
}
JavaScript

2. ใช้เพื่อทำให้บำรุงรักษาได้ง่าย

2.1 ใช้ Comment เพื่ออธิบายการทำงานที่ซับซ้อน

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

async function processOrderAndUpdateInventory(orderId) {
  try {
    // ขั้นตอนที่ 1: ดึงข้อมูลคำสั่งซื้อ
    const order = await fetchOrderDetails(orderId);
    if (!order) {
      throw new Error('ไม่พบคำสั่งซื้อ');
    }

    // ขั้นตอนที่ 2: ตรวจสอบสถานะการชำระเงิน
    const paymentStatus = await checkPaymentStatus(order.paymentId);
    if (paymentStatus !== 'completed') {
      throw new Error('การชำระเงินยังไม่เสร็จสมบูรณ์');
    }
    
    // ขั้นตอนที่ 3: อัปเดตสินค้าคงคลัง
		...
  } catch (error) {
    // บันทึกข้อผิดพลาดและคืนค่าสถานะความล้มเหลว
    console.error(`เกิดข้อผิดพลาดในการประมวลผลคำสั่งซื้อ ${orderId}:`, error);
    return { success: false, orderId, error: error.message };
  }
}
JavaScript

2.2 ใช้ Comment เพื่ออธิบายฟังก์ชันหรือเมธอด

การเขียน Comment ที่อธิบายฟังก์ชันหรือเมธอดช่วยให้ผู้อ่านโค้ดเข้าใจวัตถุประสงค์ การทำงาน และวิธีการใช้งานฟังก์ชันได้อย่างรวดเร็ว และควรใช้รูปแบบมาตรฐานเช่น JSDoc เพื่อความสม่ำเสมอและทำให้เครื่องมือต่างๆ สามารถอ่านและใช้ประโยชน์จาก Comment ได้

/**
 * คำนวณดัชนีมวลกาย (BMI)
 *
 * @param {number} weight - น้ำหนักในกิโลกรัม
 * @param {number} height - ส่วนสูงในเมตร
 * @returns {number} ค่า BMI ที่คำนวณได้
 * @throws {Error} เมื่อน้ำหนักหรือส่วนสูงมีค่าน้อยกว่าหรือเท่ากับ 0
 *
 * @example
 * const bmi = calculateBMI(70, 1.75);
 * console.log(bmi); // 22.86
 */
function calculateBMI(weight, height) {
  if (weight <= 0 || height <= 0) {
    throw new Error('น้ำหนักและส่วนสูงต้องมีค่ามากกว่า 0');
  }
  return weight / (height * height);
}
JavaScript

2.3 ใช้ Comment เพื่ออธิบายการตั้งค่าหรือค่าคงที่

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

// ค่าคงที่สำหรับการตั้งค่าความปลอดภัย
const SECURITY_CONFIG = {
  // ความยาวขั้นต่ำของรหัสผ่าน
  // ค่าสูงเพิ่มความปลอดภัย แต่อาจทำให้ผู้ใช้ไม่พอใจ
  MIN_PASSWORD_LENGTH: 8,

  // จำนวนวันก่อนที่ token จะหมดอายุ
  // ค่าต่ำเพิ่มความปลอดภัย แต่ผู้ใช้ต้องเข้าสู่ระบบบ่อยขึ้น
  TOKEN_EXPIRY_DAYS: 7
};
JavaScript

2.4 ใช้ Comment เพื่ออธิบายการทำงานที่เกี่ยวข้องกับระบบอื่น

การใช้ Comment เพื่ออธิบายการทำงานที่เกี่ยวข้องกับระบบอื่นช่วยให้ผู้พัฒนาเข้าใจความสัมพันธ์และการพึ่งพาระหว่างระบบ Comment ที่ดีควรระบุระบบที่เกี่ยวข้อง วัตถุประสงค์ของการเชื่อมต่อ และข้อควรระวังที่สำคัญ

async function syncUserData(userId) {
  // ดึงข้อมูลจากฐานข้อมูลหลัก
  const userData = await fetchUserFromMainDB(userId);

  // อัปเดตข้อมูลใน CRM
  await updateCRMSystem(userData);

  // ส่งข้อมูลไปยังระบบแจ้งเตือน
  await notifyAlertSystem(userId, 'user_updated');

  return { status: 'synced' };
}
JavaScript

2.5 ระบุแหล่งอ้างอิงของโค้ด

ในบางงานเราอาจจะจำเป็นต้องเขียนโค้ดที่ซับซ้อนมาก ๆ เพื่อแก้ปัญหาบางอย่าง โดยอาจจะได้ไอเดียหรือได้ Source Code มาจากในอินเทอร์เน็ต ซึ่งผลลัพธ์ที่ได้ออกมาอาจจะอ่านทำความเข้าใจได้ยาก การใส่ลิงก์ไปยังแหล่งที่มาของโค้ดนั้น ๆ เอาไว้ก็จะมีประโยชน์สำหรับคนที่ต้องมาทำงานต่อจากโค้ดก้อนนี้ในอนาคตแน่นอน

/**
 * OAuth Authentication setup with Passport.js
 * Source: <https://www.passportjs.org/concepts/authentication/oauth/>
 */
passport.use(new OAuth2Strategy({
    authorizationURL: '<https://provider.com/oauth2/authorize>',
    tokenURL: '<https://provider.com/oauth2/token>',
    clientID: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    callbackURL: '<https://yourapp.com/auth/provider/callback>'
  },
  function(accessToken, refreshToken, profile, done) {
    // Handle user data, e.g., find or create in the database
    User.findOrCreate({ providerId: profile.id }, function (err, user) {
      return done(err, user);
    });
  }
));
JavaScript


3. ใช้ Comment เพื่อจัดระเบียบโค้ด

3.1 แบ่งส่วนของโค้ด

การใช้ Comment เพื่อแบ่งส่วนของโค้ดช่วยเพิ่มความเป็นระเบียบและอ่านง่าย โดยเฉพาะในฟังก์ชันที่มีหลายขั้นตอน การแบ่งส่วนที่ชัดเจนช่วยให้นักพัฒนาเข้าใจลำดับการทำงานได้ง่ายขึ้น และช่วยในการบำรุงรักษาโค้ดในระยะยาว

function processUserData(userData) {
  // ==== ตรวจสอบข้อมูล ====
  if (!userData.name || !userData.email) {
    throw new Error('ข้อมูลไม่ครบถ้วน');
  }

  // ==== ทำความสะอาดข้อมูล ====
  const cleanName = userData.name.trim();
  const cleanEmail = userData.email.toLowerCase();

  // ==== สร้างรหัสผู้ใช้ ====
  const userId = generateUserId(cleanName, cleanEmail);

  // ==== บันทึกข้อมูล ====
  saveToDatabase(userId, cleanName, cleanEmail);

  return {
    id: userId,
    name: cleanName,
    email: cleanEmail
  };
}
JavaScript

3.2 ใช้ Comment พิเศษสำหรับสถานการณ์เฉพาะ

การใช้ Comment พิเศษช่วยในการสื่อสารข้อมูลสำคัญหรือสถานะของโค้ดให้กับทีมพัฒนา Comment เช่นประเภท TODO, FIXME, WARNING, และ DEBUG

function processUserData(userData) {
  // TODO: เพิ่มการตรวจสอบความถูกต้องของข้อมูลผู้ใช้
  
  // FIXME: แก้ไขการจัดการข้อผิดพลาดให้ครอบคลุมมากขึ้น
  try {
    validateUser(userData);
  } catch (error) {
    console.error(error);
  }

  // ! WARNING: ฟังก์ชันนี้ใช้ทรัพยากรสูง ควรใช้อย่างระมัดระวังกับข้อมูลขนาดใหญ่
  const processedData = heavyProcessing(userData);

  return processedData;
}
JavaScript

สรุปสั้น ๆ

การเขียน Comment ให้ดีเป็นทักษะที่สำคัญมาก ๆ ในการเขียนเขียนโค้ด โดยเฉพาะเวลาที่ต้องทำงานร่วมกับคนอื่น ๆ ลองเอาวิธีต่าง ๆ ในบทความนี้ไปปรับใช้กันดู เพื่อให้โค้ดมีคุณภาพ อ่านง่าย แล้วก็บำรุงรักษาได้ดียิ่งขึ้นครับ

Develeper

Author Develeper

More posts by Develeper
Close Menu

เราใช้คุกกี้เพื่อพัฒนาประสิทธิภาพ และประสบการณ์ที่ดีในการใช้เว็บไซต์ของคุณ คุณสามารถศึกษารายละเอียดได้ที่ นโยบายความเป็นส่วนตัว และสามารถจัดการความเป็นส่วนตัวเองได้ของคุณได้เองโดยคลิกที่ ตั้งค่า

ตั้งค่าความเป็นส่วนตัว

คุณสามารถเลือกการตั้งค่าคุกกี้โดยเปิด/ปิด คุกกี้ในแต่ละประเภทได้ตามความต้องการ ยกเว้น คุกกี้ที่จำเป็น

ยอมรับทั้งหมด
จัดการความเป็นส่วนตัว
  • คุกกี้ที่จำเป็น
    เปิดใช้งานตลอด

    ประเภทของคุกกี้มีความจำเป็นสำหรับการทำงานของเว็บไซต์ เพื่อให้คุณสามารถใช้ได้อย่างเป็นปกติ และเข้าชมเว็บไซต์ คุณไม่สามารถปิดการทำงานของคุกกี้นี้ในระบบเว็บไซต์ของเราได้
    รายละเอียดคุกกี้

  • คุกกี้สำหรับการติดตามทางการตลาด

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

บันทึกการตั้งค่า