Style Guidelines – @FordAntiTrust

พอดีว่าทำเอกสารสำหรับ 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 เป็นต้น

Comment

ทุก ๆ ไฟล์ของโปรแกรมให้เขียน 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 ตลอดทุกครั้งเพื่อง่ายต่อการนำไปใช้งาน และการแก้ไขตัวโปรแกรมในอนาคต

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

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

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

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

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

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

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

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

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

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

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

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

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

อาจวางสเตทเมนท์สั้นๆที่มีความเกี่ยวข้องกันหลายอันไว้บนบรรทัดเดียวกัน โดยใช้ 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

การตั้งชื่อตัวแปรควรตั้งให้สื่อความหมายต่อการใช้งาน และตั้งชื่อตัวแปร, ชื่อฟังค์ชั่น และชื่อตัวแปรนำเข้าค่าของฟังค์ชั่น ด้วยตัวอักษรตัวเล็กเท่านั้น และช่องว่างระหว่างคำให้ใช้ 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 อีก แต่ว่าขอเวลารวบรวมรายละเอียดอีกสักพัก เพราะว่าละเอียดพอสมควรทีเดียว

Copyright statement comment