พอดีว่าทำเอกสารสำหรับ Team Developer เมื่อนานมาแล้ว เพื่อให้ Style ในการเขียน Software ต่าง ๆ นั้นไปในทิศทางเดียวกัน เลยต้องมีการกำหนด Style ขึ้นมา เวลาทำงาน และอ่าน code จะได้ไม่ไปคนละทิศทาง มากนัก การกำหนด Style ในการเขียน นั้นไม่ได้ขึ้นอยู่กับตัวภาษาเพียงอย่างเดียว แต่ขึ้นอยู่กับ Team ของเราด้วยว่าจะกำหนดไปในทิศทางใด และง่ายต่อ Team ของเราว่าจะถนัดแนวไหนมากกว่ากัน เรามาเริ่มกันเลยแล้วกัน อาจจะขาด หรือเกินไปบ้างนั้นสุดแล้วแต่หัวหน้าของเราเองว่าจะกำหนดอะไรบ้าง และสิ่งที่ผมได้รวบรวมมานี้ เป็นการเขียนที่ได้ผ่านการขัดเกามามากพอสมควร และผ่านการใช้งานโดยส่วนตัวมามาก ว่าทำงานได้เร็วและเข้าใจได้ง่ายต่อตนเอง และคาดว่าน่าจะทำให้คนอื่นๆ ที่เข้ามาอ่าน Code ของเราเข้าใจได้ง่ายด้วยเช่นกัน
PHP Programming’s Style Guidelines
เป็นการกำหนดรูปแบบการเขียน ของโปรแกรมเพื่อให้โปรแกรมอ่านง่าย และพัฒนาต่อได้โดยที่ไม่จำเป็นต้องมาปรับแต่งหรืออ่านทำความเข้าใจใหม่ ประกอบด้วย
- Version, Changelog, Readme และ License
- การตั้ง 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 เป็นส่วนใหญ่
- การทำChangelog เพื่อเป็นการสร้างเอกสารเพื่อแสดงถึงความคืบหน้า และรวมถึงการแก้ไขข้อผิดพลาดต่าง ๆ โดยทุก ๆ ครั้งที่ มีรูปแบบดังนี้
Software version August 10, 2004
=========================================================
August 2004:
——————————————————————————–
! fixs bug in function xxx in fileName.php
+ add new function to program.
=========================================================
- การทำไฟล์ Readme จะทำก็ต่อเมื่อโปรแกรมนั้นพร้อมใช้งานได้แล้วในระดับหนึ่ง โดยในไฟล์นี้จะระบุรูปแบบคือ การติดตั้ง, ทีมงาน หรือผู้จัดทำ, ประวัติงานต่าง ๆ
การทำไฟล์ License - เป็นการบ่งบอกว่าโปรแกรมนี้ยึดหลักการลิขสิทธิ์แบบใดในการคุ้มครองตัวโปรแกรมนี้ เช่น GNU/GPL ของ Free Software Foundation เป็นต้น
- ทุก ๆ ไฟล์ของโปรแกรมให้เขียน 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. *
* *
******************************************************************************/
- การแก้ไขไฟล์โดยต้องใส่ 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
- เพื่อง่ายต่อการอ่านก็ได้ และในทุกคลาส, ฟังค์ชั่น และตัวแปรที่ประกาศครั้งแรก ให้ทำการเขียน comment ตลอดทุกครั้งเพื่อง่ายต่อการนำไปใช้งาน และการแก้ไขตัวโปรแกรมในอนาคต
- Tab character สำหรับแทรกระหว่างกั้นหน้าซ้ายกับอักษรแรกของแต่ละบรรทัด ได้จากปุ่ม Tab
- ควรตั้งความกว้าง tab ไว้ที่ 4 ตัวอักษร น้อยกว่านี้จะอ่านยาก มากกว่านี้จะกินที่ อีกเหตุผลคือนี่เป็นตัวเลขที่โปรแกรมเมอร์ส่วนใหญ่เขาใช้กัน ฝึกสายตาให้คุ้นกับค่ามาตรฐานย่อมได้เปรียบ
- สำหรับบรรทัดแรกให้เริ่มพิมพ์อักษรแรกที่คอลัมน์ 0 ชิดกับกั้นหน้าซ้ายเสมอ
- เมื่อขึ้นบรรทัดใหม่ หากไม่มีเหตุผลอะไรเป็นพิเศษให้จัดย่อหน้าให้ตรงกับบรรทัดก่อนหน้า เพื่อสื่อว่าสองบรรทัดนี้ความสำคัญอยู่ในระดับเดียวกัน
- เมื่อเปิดบล็อกใหม่ด้วยปีกกาเปิด (‘{‘) ต้องเพิ่ม tab ให้บรรทัดถัดไปหนึ่งขั้น เพื่อสื่อว่าบรรทัดหลังเป็น subordinate ของบรรทัดก่อนหน้า
- เมื่อจะปิดบล็อกด้วยปีกกาปิด (‘}’) ให้ขึ้นบรรทัดใหม่ ลด tab ลงหนึ่งขั้นแล้วจึงพิมพ์ปีกกาปิด เพื่อสื่อว่าบรรทัดถัดไปจะไม่เป็น subordinate อย่างบรรทัดก่อนหน้าอีกแล้ว หากบรรทัดที่พิมพ์ปีกกาปิดนั้นไม่มีปีกกาเปิดต่อท้าย ให้เริ่มบรรทัดใหม่ที่ tab ตรงกับปีกกาปิดได้ทันที
- เคาะ space เพียงครั้งเดียวสำหรับตำแหน่งที่ต้องการ space เพื่อประหยัดเนื้อที่และคีย์สโตรก
- เคาะ space กั้นชื่อคลาส, เมธอด, ตัวแปร, ค่าป้อน, คีย์เวิร์ดโอเปอเรเตอร์, ปีกกาปิด/เปิด ฯลฯ
- เคาะ space ตามหลังจุลภาค (‘,’) ที่กั้นระหว่างไอเทมในลิสต์
- อย่าแทรก space ระหว่าง dot operator (‘.’) กับ identifiers (ชื่อคลาส ชื่ออินสแตนซ์ ชื่อเมธอดและชื่อฟิลด์) เพราะ dot operator มีไว้เพื่อเชื่อมสองสิ่งให้กลายเป็นสิ่งใหม่ที่มีความหมายต่างจากเดิม
- ขึ้นบรรทัดใหม่เมื่อจบสเตทเมนท์ปกติ
- แต่ละตำแหน่งที่ต้องการบรรทัดว่างให้แทรกบรรทัดว่างเพียงบรรทัดเดียวเท่านั้น เพื่อประหยัดเนื้อที่และคีย์สโตรก
- จัดกลุ่มของสเตทเมนท์ที่เกี่ยวข้องกันเป็นหนึ่งหน่วยความคิด อย่าแทรกบรรทัดว่างลงไปแยกหนึ่งหน่วยความคิดนี้ออกจากกันเด็ดขาด
- แทรกบรรทัดว่างลงไปตรงกลางแยกสองหน่วยความคิดออกจากกัน
- แทรกบรรทัดว่างระหว่างบล็อกหลักของคลาส เช่น บล็อกของการประกาศชื่อฟิลด์ บล็อกของคอนสตรักเตอร์ บล็อกของเมธอด ฯลฯ
-
ข้อแนะนำ tab และ space
- อย่าใช้ space ในตำแหน่งที่ควรจะใช้ tab ด้วยเหตุผลหลักสองข้อ
- ประหยัดคีย์สโตรก คุณต้องเคาะ space สี่ครั้งจึงจะได้ช่องว่างเท่ากับ tab หนึ่งครั้ง
- โปรแกรมเมอร์ a อาจจะตั้งความกว้าง tab ไว้ที่ 4 ตัวอักษร ขณะที่โปรแกรมเมอร์ b ตั้งไว้ที่ 6 ตัวอักษร เมื่อมีการส่งไฟล์ให้กันจะไม่เกิดปัญหา"ความกว้าง tab ที่ไม่คุ้นตา"
- หากหนึ่งสเตทเมนท์ยาวเกินกว่าหนึ่งบรรทัด ให้ปัดส่วนเกินของสเตทเมนท์มาไว้ในบรรทัดถัดไป และเพิ่ม tab จากต้นสเตทเมนท์ขึ้นหนึ่งหรือสองขั้น เพื่อเป็นจุดสังเกตว่าสเตทเมนท์นี้มีความยาวมากกว่าปกติ
- อาจวางสเตทเมนท์สั้นๆที่มีความเกี่ยวข้องกันหลายอันไว้บนบรรทัดเดียวกัน โดยใช้ 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 { ………… } |
- การตั้งชื่อตัวแปรควรตั้งให้สื่อความหมายต่อการใช้งาน และตั้งชื่อตัวแปร, ชื่อฟังค์ชั่น และชื่อตัวแปรนำเข้าค่าของฟังค์ชั่น ด้วยตัวอักษรตัวเล็กเท่านั้น และช่องว่างระหว่างคำให้ใช้ Underscore ในการเว้นช่องว่าง ระหว่างคำ เช่น $current_user, print_login_status(), do_stuff($value_name) ห้ามใช้ $currentuser และ $currentUser
- ในภาษา PHP นั้นไม่มีการกำหนด Type ที่แน่นอน จึงไม่ต้องระบุ Type ด้านหน้าตัวแปร เช่น intMember แบบในภาษาอื่น ๆ แต่มีข้อยกเว้นในส่วนของ array และ object ควรใส่เพื่อบ่งบอกว่าเป็น array หรือ object ด้วย เช่น array แทนด้วย arr_var_name และ object แทนด้วย obj_var_name เปนต้น
- ตัวแปรนับรอบ 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 อีก แต่ว่าขอเวลารวบรวมรายละเอียดอีกสักพัก เพราะว่าละเอียดพอสมควรทีเดียว