Developer

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

---

PHP Programming’s Style Guidelines

เป็นการกำหนดรูปแบบการเขียน ของโปรแกรมเพื่อให้โปรแกรมอ่านง่าย และพัฒนาต่อได้โดยที่ไม่จำเป็นต้องมาปรับแต่งหรืออ่านทำความเข้าใจใหม่ ประกอบด้วย

1. Version, Changelog, Readme และ License

1. การตั้ง version ไม่มีกฎตายตัวในการตั้ง แต่ที่จะแนะนำในเอกสารฉบับนี้ก็คือ version ของโปรแกรมจะใช้ทศนิยมจำนวน 2 จุดเพื่อบ่งบอกการพัฒนาของโปรแกรม ให้ไล่จาก ทศนิยมจุดที่ 2 เช่น 0.0.1 โดยทศนิยมจุดที่ 2 คือการแก้ไขข้อผิดพลาด อันเกิดจากการ coding หรือการ flow โปรแกรมที่ผิดพลาดไป และเป็นการประกาศเริ่มต้นการพัฒนาไปในตัวด้วย หรืออาจจะใช้ a – z ต่อท้ายตัวเลขก่อนเพื่อบ่งบอกการใส่ฟังค์ชั่น หรือการแก้ไขในการเริ่มต้นพัฒนาก็ได้ ส่วนทศนิยมจุดที่ 1 นั้นเป็นการเพิ่มฟังค์ชั่น, เพิ่มคลาสต่าง ๆ เข้าไปใหม่ เพื่อเพิ่มความสามารถของโปรแกรม ส่วนตำแหน่งหน่วยนั้นเป็นการประกาศ version release เพื่อบ่งบอกว่าโปรแกรมพร้อมใช้งานในทุก ๆ ด้านโดยไม่ขาดตกบกพร่องในขั้นตอนการใช้งานจริงจากกลุ่มทดสอบแล้ว แต่อาจมีข้อผิดพลาดตามมาได้เช่นกันหลังจากประกาศ version release ไปแล้ว เพราะไม่มีโปรแกรมใดสมบูรณ์แบบที่สุด แต่ถือความสำเร็จจากผลของการใช้งานในช่วงของการทดสอบของกลุ่มทดสอบเป็นสำคัญ แต่โดยส่วนใหญ่แล้ว version แรกที่ส่งออกสู่ผู้ใช้มักจะเป็น version ที่ลงท้ายตัว alpha และต่อมาก็ตามด้วย beta ขึ้นอยู่กับผู้พัฒนาจะเลือกตัวไหนมาใช้ หรือใช้ตามลำดับทั้งสองตัวก็ได้ แต่หมายเลข version ในครั้งแรกจะเริ่มที่ 0.0.1 alpha เป็นส่วนใหญ่
2. การทำChangelog เพื่อเป็นการสร้างเอกสารเพื่อแสดงถึงความคืบหน้า และรวมถึงการแก้ไขข้อผิดพลาดต่าง ๆ โดยทุก ๆ ครั้งที่ มีรูปแบบดังนี้

   Software version August 10, 2004

   =========================================================

   August 2004:

   ——————————————————————————–

   ! fixs bug in function xxx in fileName.php

   + add new function to program.

   =========================================================

3. การทำไฟล์ Readme จะทำก็ต่อเมื่อโปรแกรมนั้นพร้อมใช้งานได้แล้วในระดับหนึ่ง โดยในไฟล์นี้จะระบุรูปแบบคือ การติดตั้ง, ทีมงาน หรือผู้จัดทำ, ประวัติงานต่าง ๆ
   การทำไฟล์ License
4. เป็นการบ่งบอกว่าโปรแกรมนี้ยึดหลักการลิขสิทธิ์แบบใดในการคุ้มครองตัวโปรแกรมนี้ เช่น GNU/GPL ของ Free Software Foundation เป็นต้น

Comment

1. ทุก ๆ ไฟล์ของโปรแกรมให้เขียน Copyright statement comment ทุกครั้งบนหัวของโปรแกรมทุก ๆ ไฟล์ไม่ว่าจะเป็นไฟล์ใดก็ตาม โดยในนั้นจะมีระบุชื่อไฟล์นั้น ๆ ก่อน ตามด้วยชื่อของโปรแกรมต่าง ๆ ตามตัวอย่างนี้
   

   Copyright statement comment

   /*******************************************************************************

   * fileName.php *

   ********************************************************************************

   * Software name with short name : Software name with long name *

   * Project Inspired by Your Name ([email protected]) *

   * ======================================================= *

   * Software Version: Software 0.0.1 *

   * Software by: Software *

   * Copyright 2005-2006 by: Software *

   * Support, News, Updates at: http://www.website.org *

   ********************************************************************************

   * This program is free software; you may redistribute it and/or modify it *

   * under the terms of the provided license as published by Open-Source. *

   * *

   ******************************************************************************/

2. การแก้ไขไฟล์โดยต้องใส่ comment คือการแก้ไขไฟล์เพื่อแก้ไขบัก หรือข้อผิดพลาดของโปรแกรมนั้น ๆ เพื่อง่ายต่อการไล่การพัฒนาการของโปรแกรมนั้น ๆ เช่น
   

   # This function is casting Date and Time from MySQL DateTime.

   หรือถ้าต้องการหลายบรรทัดก็ให้ใช้
   
   

   # I imagine this file will eventually become a backwards

   # compatibility wrapper around a load balancer object, and

   # the load balancer will finally call Database, which will

   # represent a single connection

   
   

3. เพื่อง่ายต่อการอ่านก็ได้ และในทุกคลาส, ฟังค์ชั่น และตัวแปรที่ประกาศครั้งแรก ให้ทำการเขียน comment ตลอดทุกครั้งเพื่อง่ายต่อการนำไปใช้งาน และการแก้ไขตัวโปรแกรมในอนาคต

Indentation Style (Code Layout, Tabs และ Spaces)

1. Tab character สำหรับแทรกระหว่างกั้นหน้าซ้ายกับอักษรแรกของแต่ละบรรทัด ได้จากปุ่ม Tab

1. ควรตั้งความกว้าง tab ไว้ที่ 4 ตัวอักษร น้อยกว่านี้จะอ่านยาก มากกว่านี้จะกินที่ อีกเหตุผลคือนี่เป็นตัวเลขที่โปรแกรมเมอร์ส่วนใหญ่เขาใช้กัน ฝึกสายตาให้คุ้นกับค่ามาตรฐานย่อมได้เปรียบ
2. สำหรับบรรทัดแรกให้เริ่มพิมพ์อักษรแรกที่คอลัมน์ 0 ชิดกับกั้นหน้าซ้ายเสมอ
3. เมื่อขึ้นบรรทัดใหม่ หากไม่มีเหตุผลอะไรเป็นพิเศษให้จัดย่อหน้าให้ตรงกับบรรทัดก่อนหน้า เพื่อสื่อว่าสองบรรทัดนี้ความสำคัญอยู่ในระดับเดียวกัน
4. เมื่อเปิดบล็อกใหม่ด้วยปีกกาเปิด (‘{‘) ต้องเพิ่ม tab ให้บรรทัดถัดไปหนึ่งขั้น เพื่อสื่อว่าบรรทัดหลังเป็น subordinate ของบรรทัดก่อนหน้า
5. เมื่อจะปิดบล็อกด้วยปีกกาปิด (‘}’) ให้ขึ้นบรรทัดใหม่ ลด tab ลงหนึ่งขั้นแล้วจึงพิมพ์ปีกกาปิด เพื่อสื่อว่าบรรทัดถัดไปจะไม่เป็น subordinate อย่างบรรทัดก่อนหน้าอีกแล้ว หากบรรทัดที่พิมพ์ปีกกาปิดนั้นไม่มีปีกกาเปิดต่อท้าย ให้เริ่มบรรทัดใหม่ที่ tab ตรงกับปีกกาปิดได้ทันที

Space characterสำหรับแทรกระหว่างอะไรก็ตามที่ควรแทรกในระหว่างบรรทัด ได้จาก Space Bar

1. เคาะ space เพียงครั้งเดียวสำหรับตำแหน่งที่ต้องการ space เพื่อประหยัดเนื้อที่และคีย์สโตรก
2. เคาะ space กั้นชื่อคลาส, เมธอด, ตัวแปร, ค่าป้อน, คีย์เวิร์ดโอเปอเรเตอร์, ปีกกาปิด/เปิด ฯลฯ
3. เคาะ space ตามหลังจุลภาค (‘,’) ที่กั้นระหว่างไอเทมในลิสต์
4. อย่าแทรก space ระหว่าง dot operator (‘.’) กับ identifiers (ชื่อคลาส ชื่ออินสแตนซ์ ชื่อเมธอดและชื่อฟิลด์) เพราะ dot operator มีไว้เพื่อเชื่อมสองสิ่งให้กลายเป็นสิ่งใหม่ที่มีความหมายต่างจากเดิม

Newline character ได้จากปุ่ม Enter

1. ขึ้นบรรทัดใหม่เมื่อจบสเตทเมนท์ปกติ
2. แต่ละตำแหน่งที่ต้องการบรรทัดว่างให้แทรกบรรทัดว่างเพียงบรรทัดเดียวเท่านั้น เพื่อประหยัดเนื้อที่และคีย์สโตรก
3. จัดกลุ่มของสเตทเมนท์ที่เกี่ยวข้องกันเป็นหนึ่งหน่วยความคิด อย่าแทรกบรรทัดว่างลงไปแยกหนึ่งหน่วยความคิดนี้ออกจากกันเด็ดขาด
4. แทรกบรรทัดว่างลงไปตรงกลางแยกสองหน่วยความคิดออกจากกัน
5. แทรกบรรทัดว่างระหว่างบล็อกหลักของคลาส เช่น บล็อกของการประกาศชื่อฟิลด์ บล็อกของคอนสตรักเตอร์ บล็อกของเมธอด ฯลฯ
6. ข้อแนะนำ tab และ space

1. อย่าใช้ space ในตำแหน่งที่ควรจะใช้ tab ด้วยเหตุผลหลักสองข้อ

1. ประหยัดคีย์สโตรก คุณต้องเคาะ space สี่ครั้งจึงจะได้ช่องว่างเท่ากับ tab หนึ่งครั้ง
2. โปรแกรมเมอร์ a อาจจะตั้งความกว้าง tab ไว้ที่ 4 ตัวอักษร ขณะที่โปรแกรมเมอร์ b ตั้งไว้ที่ 6 ตัวอักษร เมื่อมีการส่งไฟล์ให้กันจะไม่เกิดปัญหา"ความกว้าง tab ที่ไม่คุ้นตา"

แต่คุณอาจจะใช้ tab แทน space ก็ได้ เมื่อต้องจัดคอลัมน์ของเทกซ์ให้ตรงกัน เช่น เมื่อคุณต้องป้อนค่าเริ่มต้นให้ตัวแปรในลักษณะตาราง หากคอลัมน์ตรงกัน การอ่านหรือแก้ไขข้อมูลในตารางก็ง่ายขึ้น

ข้อแนะนำ tab และ newline

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

ข้อแนะนำ space และ newline

1. อาจวางสเตทเมนท์สั้นๆที่มีความเกี่ยวข้องกันหลายอันไว้บนบรรทัดเดียวกัน โดยใช้ space กั้นระหว่างสเตทเมนท์

ตัวอย่างต่าง ๆ

<?php     ………… ?> <?php echo($XXX);?> ห้ามใช้ <?=$XXX?> if(condition) {     ………… } elseif(condition) {     ………… } else {     ………… } for($i=0; $i< $x ; $i++) {     ………… }

do  {     ………… } while (condition) while(condition) {     ………… } function functionName () {     ………… } class className {     ………… }

Variable Names, Function Names และ Function Arguments

1. การตั้งชื่อตัวแปรควรตั้งให้สื่อความหมายต่อการใช้งาน และตั้งชื่อตัวแปร, ชื่อฟังค์ชั่น และชื่อตัวแปรนำเข้าค่าของฟังค์ชั่น ด้วยตัวอักษรตัวเล็กเท่านั้น และช่องว่างระหว่างคำให้ใช้ Underscore ในการเว้นช่องว่าง ระหว่างคำ เช่น $current_user, print_login_status(), do_stuff($value_name) ห้ามใช้ $currentuser และ $currentUser
2. ในภาษา PHP นั้นไม่มีการกำหนด Type ที่แน่นอน จึงไม่ต้องระบุ Type ด้านหน้าตัวแปร เช่น intMember แบบในภาษาอื่น ๆ แต่มีข้อยกเว้นในส่วนของ array และ object ควรใส่เพื่อบ่งบอกว่าเป็น array หรือ object ด้วย เช่น array แทนด้วย arr_var_name และ object แทนด้วย obj_var_name เปนต้น
3. ตัวแปรนับรอบ Loop, Loop counter หรือ Loop Indices ให้ใช้ตัวแปรที่มีขนาดตัวอักษรที่สื่อความหมายเท่านั้น โดยใช้คำว่า index_counter ขึ้นต้นเสมอ เช่น $index_counter_member เป็นต้น

---

ทั้งหมดทั้งปวงนี้เป็นเพียงแค่ส่วนหนึ่งของ Style ที่ทำการรวบรวมมาไว้ อาจจะยังไม่ครบทั้งหมดในกระบวนการ แต่ว่าก็เพียงพอต่อการทำงานเป็น Team ได้บ้างแล้ว

ปรับแต่งเนื้อหาให้ใช้งานได้ดีขึ้นจาก indentation style in Java programming ( http://www.intellectworld.com/thai/indentation.html )

จริงๆ ยังเหลือ Tags Manual อีก แต่ว่าขอเวลารวบรวมรายละเอียดอีกสักพัก เพราะว่าละเอียดพอสมควรทีเดียว