สร้าง document ให้โค้ดที่เขียนแบบมืออาชีพ

สร้าง document ให้โค้ดที่เขียนแบบมืออาชีพ

เคยเห็น php class ต่างๆหรือเปล่าครับ ที่เค้าทำเอกสารเอาไว้ให้เราอ่านเข้าใจได้ง่ายๆ แบ่งแยกตาม class , function บรรยายตัวแปร ,parameter, output เอาไว้ได้อย่างครบถ้วน รวมทั้งมีการลิ้งค์ไปยัง class ที่เกี่ยวข้องอีกต่างหาก ถ้าไม่เคยเห็น ผมจะยกตัวอย่างของจริง ที่อาจจะผ่านหูผ่านตามาบ้างแล้ว เช่น

 ถ้าสังเกตจะเห็นว่าหน้าตาออกมาเหมือนกันเลย ทั้งๆที่คนเขียนโค้ดทั้งสองระบบเป็นคนละคนกัน แล้วถ้าได้เปิดอ่านเนื้อหาภายในจะเห็นว่าเค้าอธิบาย class function parameter และอื่นๆเอาไว้ละเอียดพอสมควรเลย ถึงแม้ว่าจะไม่ถึงกับทำให้คนที่ไม่รู้เรื่องเลย สามารถรู้เรื่องทั้งหมดได้ก็ตาม แต่สำหรับ programmer ที่ต้องเข้าไปยุ่งเกี่ยวกับระบบนั้นๆ document เหล่านี้ช่วยได้พอสมควรเลยครับ ในการทำความเข้าใจ ปรับแต่ง และเพิ่มเติมระบบ จากที่มีอยู่เดิม

เอกสารที่ได้อ่านตามตัวอย่างที่ได้ส่งให้ดูนั้น เชื่อหรือไม่ครับ ว่าเค้าใช้เวลาสร้างไม่น่าจะเกิน 5 นาที ถึงแม้ว่าโค้ดจะมีการแก้เดือนละครั้งก็ตาม document พวกนี้ก็จะถูก update ตามทุกครั้งที่แก้ได้ในเวลาไม่ถึง 5 นาทีทุกครั้ง เรียกได้ว่า แก้โค้ดเมื่อไร ก็อัพ document ได้แทบจะทันทีเลยทีเดียวเชียวล่ะ

โดย document เหล่านี้ ผมจะสรุปประโยชน์ให้มีคร่าวๆดังนี้

  • ศึกษาระบบได้เร็วขึ้น - หากมีโค้ดในเมื่อด้วย และต้องการไล่โค้ด การอ่าน document เหล่านี้จะช่วยได้มากๆ เพราะรู้การทำงาน ในแต่ละจุดโดยที่ไม่ต้องแปลงร่างตัวเองให้เป็น compiler เลยแม้แต่น้อย
  • แก้ไขระบบได้เร็วขึ้น - เพราะเอกสารเหล่านี้จะบอก ว่า function ที่ทำงานนี้มีการเชื่อมโยงกับระบบที่เกี่ยวข้องอย่างไร และจุดใด และเราก็คลิกไปดูการทำงานของส่วนที่เกี่ยวข้องได้อีก ว่าทำงานอย่างไรทำให้เราแก้ไขเอกสารได้อย่างรวดเร็วมาก
  • เพิ่มเติมระบบได้ง่าย - เพราะเราจะรู้ว่าทั้งๆระบบประกอบด้วยส่วนไหนบ้าง แต่ละส่วนทำหน้าที่อย่างไร และตัวช่วยที่เค้าเตรียมไว้ให้เราประกอบด้วยอะไรบ้าง ทำงานอย่างไร ต้องป้อนค่าอะไร และรับค่าอะไร เรียกว่ามากันครบ
  • เป็นส่วนหนึ่งในการส่งมอบงาน - ในระบบงานที่ใหญ่ๆแล้ว การทำงานแล้วส่งมอบ document เหล่านี้ จะถือว่าเป็นส่วนหนึ่งในการส่งมอบงานด้วย
  • คนแก้ไม่ปวดหัว - เพราะหากระบบที่จะต้องแก้ ไม่มี document ก็ปวดหัวแล้ว ยิ่งถ้าเจอคนที่เขียนโค้ดไม่เคย comment ในการทำงานด้วย รับรอง การแก้จะเป็นอะไรที่ยากกว่าการเขียนใหม่อย่างแน่นอน หรือแม้กระทั่งตัวเองที่จะหลับมาแก้ภายหลังก็ตาม
  • ใช้ในการอ้างอิง เวลาสื่อสารได้ - เพราะว่าหากเราไม่มีเอกสารอ้างอิงเหล่านี้ หากจะต้องสื่อสารให้กับทีมงานทำ ก็จะเสียเวลาอธิบายกันนาน หากมีเอกสารนี้แล้ว ผู้ร่วมทีมก็แค่อ่านก็เข้าใจตรงกันแล้วไม่จำเป็นต้องพูดคุยกันเลย
  • เป็นส่วนหนึ่งของ programmer ที่ดี มีมาตรฐานในการทำงาน คงไม่ต้องอธิบายเพิ่มมั้งครับ 

 ถ้ามีข้อดีอย่างนี้แล้ว ทำไมเราจะไม่ใช้มันล่ะ? แล้วอยากรู้มั้ย ว่าจะใช้มันได้อย่างไร? ไม่ยากครับ ไม่ยากจริงๆ เริ่มต้นจาก โหลดตัวช่วยของเรามาก่อน นั่นก็คือ phpdocumentor โดยเลือกเอา version ใหม่ๆนะครับ จริงๆแต่ละ version ไม่ต่างกันมากหรอกครับ โดยตลอดบทความนี้ ผมใช้ version 1.4.3

เมื่อ download zip ไฟล์มาแล้ว ให้แตกออกมาเป็นแฟ้มเก็บไว้ที่ localhost ในเครื่องเราเลยนะครับ เปลี่ยนชื่อแฟ้มเป็นอะไรก็ได้ตามที่ต้องการเลย ตัวอย่างผมแตกเอาไว้ในชื่อ PhpDocumentor ดังนั้นแปลว่าเมื่อผมจะเรียกใช้งาน ผมก็จะเรียกที่ http://127.0.0.1/PhpDocumentor ซึ่งจะต้องเปิดเจอหน้าเว็บนะครับ สำหรับคนที่ยังไม่ทราบว่า localhost คืออะไร มันเป็นอย่างไรแนะนำให้ไปอ่าน จำลองเครื่องตัวเองเป็น server ด้วย WAMP

เมื่อถึงตรงนี้ ถือว่าทุกท่านเปิดหน้าเว็บ http://127.0.0.1/PhpDocumentor กันได้แล้ว จะได้หน้าแต่แบบนี้


จากนั้นให้เรามาตั้งค่ากันก่อน โดยสมมุติว่าเรามีไฟล์เว็บเรา เก็บที่ http://localhost/demo/ และเราต้องการให้สร้าง document ของเว็บนี้ ดังนั้น ผมต้องเริ่มที่การตั้งค่าก่อนครับ ดังนี้

ตัวอย่าง http://localhost/demo/ นี้ เก็บไฟล์ที่ D:\wamp\www\demo\ โดย path root เว็บของเครื่องผมคือ D:\wamp\www ซึ่งถ้าเป็นเครื่องปกติ จะเป็น C:\wamp\www ดังนั้นไม่ต้องสับสนในการอธิบายว่าเป็น D:\wamp\www ครับ

ให้ทำการ copy configuration ในการสร้าง document ที่เราต้องการออกมาเป็นไฟล์ใหม่ โดยไฟล์ configuration เก็บอยู่ที่ D:\wamp\www\PhpDocumentor\user\ เมื่อเปิดมาแล้วจะพบว่ามีไฟล์ default.ini, demo.ini, error.ini, makedocs.ini, pear-makedocs.ini, testdocbook.ini โดยผมจะ copy ไฟล์ default.ini แล้วมาสร้างใหม่ตั้งชื่อไฟล์ว่า bee.ini เลยครับ ทำให้เราจะมีไฟล์ bee.ini เพิ่มขึ้นมาอีกในแฟ้มนี้

ให้เปิดไฟล์ configuration bee.ini จากที่เราสร้างขึ้นมาใหม่เมื่อสักครู่ โดยแก้ไขค่าในจุดต่างๆดังนี้

  • target = "D:/wamp/www/demo/docs"
  • directory = "D:/wamp/www/demo/"
  • output = HTML:frames:earthli

 นอกเหนือจากนี้ก็ใช้ค่าเดิมครับ ยังไม่ต้องแก้อะไร และอย่างลืมนะครับ ว่าเครื่องท่านเก็บ root path ที่ไหน แก้ไขให้ตรงด้วยครับ จากนั้น ให้ refresh หน้า http://127.0.0.1/PhpDocumentor อีกครั้ง แล้วกดที่ tab Config แล้วเลือก bee.ini หรือไฟล์ที่พึ่งสร้างเมื่อสักครู่นี้นั่นเอง จากนั้นกด OK เลยครับ **ขั้นตอนนี้คือการสร้าง document ครับ


 ถ้าไม่มีอะไรผิดพลาดจะได้หน้าตาประมาณนี้ **ข้อความไม่จำเป็นต้องเหมือน เพราะว่าข้อความที่ปรากฏใน document ขึ้นอยู่กับ Coding และ comment ที่เขียนครับ


ถ้ารายละเอียดมีน้อยมาก ไม่ต้องตกใจนะครับ เพราะว่ารายละเอียดที่จะปรากฏใน document เหล่านี้ เกิดมาจากที่ท่านได้ทำการ comment เอกสารตามรูปแบบนั่นเองครับ ซึ่งเดี๋ยวจะมาบอกอีกครั้ง แต่ตอนนี้กลับมาแต่งหน้าตากันก่อน เพราะว่ามันเละ แล้วยังมี error อีกด้วย

การแก้ไขหน้าตาให้สวยงามทำได้โดยเปิดแฟ้ม D:\wamp\www\PhpDocumentor\phpDocumentor\Converters\HTML\frames\templates\earthli\templates ขึ้นมา แล้วจะพบว่ามีหลายไฟล์ที่มีนามสกุล .tp ให้เปลี่ยนเป็น .tpl ทั้งหมด จากนั้นให้เปิดแฟ้ม media หรือที่ D:\wamp\www\PhpDocumentor\phpDocumentor\Converters\HTML\frames\templates\earthli\templates\media จะพบ banner.cs ให้เปลี่ยนเป็น banner.css และเปลี่ยน stylesheet.cs ให้เป็น stylesheet.css จากนั้นให้เปิดแฟ้ม images หรือ D:\wamp\www\PhpDocumentor\phpDocumentor\Converters\HTML\frames\templates\earthli\templates\media\images เปลี่ยนไฟล์ นามสกุล .pn ทั้งหมดให้เป็น .png

จากนั้นให้เราสร้าง document ใหม่โดยเลือก bee.ini กด OK เหมือนขั้นตอนด้านบนที่ได้เคยทำไปแล้วนั่นล่ะครับ


จะเห็นว่าหน้าตาดีขึ้นเยอะเลย แล้วครั้งต่อไป เมื่อเราต้องการสร้างเอกสารใหม่ ก็แค่เลือก bee.ini แล้วกด ok แค่นั้นเองครับ ระบบจะตรวจจับการเปลี่ยนแปลงให้เองตามโค้ดที่เราเขียนเลย

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

<?php  if ( ! defined('BASEPATH')) exit('No direct script access allowed'); /**  * CodeIgniter  *  * An open source application development framework for PHP 4.3.2 or newer  *  * @package CodeIgniter  * @author ExpressionEngine Dev Team  * @copyright Copyright (c) 2008 - 2009, EllisLab, Inc.  * @license http://codeigniter.com/user_guide/license.html  * @link http://codeigniter.com  * @since Version 1.3  * @filesource  */ /**  * CI_BASE - For PHP 4  *  * This file is used only when CodeIgniter is being run under PHP 4.  *  * In order to allow CI to work under PHP 4 we had to make the Loader class  * the parent of the Controller Base class.  It's the only way we can  * enable functions like $this->load->library('email') to instantiate  * classes that can then be used within controllers as $this->email->send()  *  * PHP 4 also has trouble referencing the CI super object within application  * constructors since objects do not exist until the class is fully  * instantiated.  Basically PHP 4 sucks...  *  * Since PHP 5 doesn't suffer from this problem so we load one of  * two files based on the version of PHP being run.  *  * @package CodeIgniter  * @subpackage codeigniter  * @category front-controller  * @author ExpressionEngine Dev Team  * @link http://codeigniter.com/user_guide/  */  class CI_Base extends CI_Loader { function CI_Base() { // This allows syntax like $this->load->foo() to work parent::CI_Loader(); $this->load =& $this; // This allows resources used within controller constructors to work global $OBJ; $OBJ = $this->load; // Do NOT use a reference. } } /* End of file Base4.php */ /* Location: ./system/codeigniter/Base4.php */

 โดยโค้ดนี้ผมตัดมาจากส่วนหนึ่งของ CodeIgniter ซึ่งเป็นตัวอย่างที่ดี สามารถ copy นำไปเป็นไฟล์ทดสอบเพื่อสร้าง document ได้เลยครับ โดยส่วนที่ปรากฏเป็นรายละเอียดก็คือใน comment ด้านบนนั่นเอง ซึ่งเป็นตัวอย่างการเขียนโค้ดที่ดี โดยทั้งนี้ก็อิง syntag ได้ตามคู่มือที่ผมลิ้งค์ไว้ให้ได้เลยครับ

รับรองครับ ว่าเสียเวลาเขียน comment แต่มันคุ้มค่ามากมายแบบสุดๆแน่นอน เชื่อโพ้มมมมมมม

เวลาที่เอาเอกสารระบบให้คนอื่นดูก็ copy แฟ้ม docs ไปได้เลยครับ เป็น HTML เลย นอกจากนี้หากศึกษาการตั้งค่าเพิ่มจะเห็นว่าสามารถ export ออกมาเป็น PDF , CHM หรือเป็นระบบ template ได้อีก มันแจ่มมากๆเลยครับขอบอก

Create: Modify : 2011-01-06 11:10:07 Read : 6880 URL :