קוד טוב הוא קוד מתועד ומוער היטב. כאשר אני כותב 'מוער' אני מתכוון להערות. הערות חשובות במיוחד הן עבור המתכנת עצמו והן עבור מתכנתים אחרים.
עבור מתכנתים אחרים התועלת ברורה, אך התועלת עצומה גם כלפי המתכנת עצמו. ראשית, הערות טובות מסייעות גם למי שכתב אותן אם הוא נדרש לגעת בקוד אחרי תקופה ארוכה. שנית, הערות שכתובות בפורמט מתאים יכולות לסייע מאד בשלב התיעוד אם משתמשים בתוכנת Doxygen. קוד עם הערות ברורות וסדורות ובנוסף לו גם דוקומנטציה מסודרת מוסיפים המון ערך לקוד. מתכנתים שכותבים הערות ותיעוד נחשבים למתכנתים מעולים, לפיכך כדאי לסגל את הרגל התיעוד עד שיהפוך לטבע שני לתכנות.
כתיבת ההערות בפורמט מסוים מאפשרות לנו להשתמש בתוכנת Doxygen כדי לייצר מסמכי תיעוד אוטומטיים מהקוד עצמו. איך המסמכים האלו נראים? שימו לב למסמכי התיעוד של מדיה-ויקי – תוכנה שכתובה ב-PHP.
ניתן להשתמש ב-Doxygen בכל שפה, ההדגמה שאני אדגים כאן היא ב-PHP, אך כמובן שניתן להשתמש בה ב-Java, C++, Python וכו'.
התקנת Doxygen על לינוקס
אם יש לכם שרת פיתוח מבוסס לינוקס (ולמה שלא יהיה לכם? שימו לב כמה קל להתקין!), קל מאד להתקין Doxygen:
sudo apt-get install doxygen
אגב, קל גם להתקין Doxygen על חלונות, הורידו את קובץ ה-doxygen בדף ההורדות ועקבו אחר ההוראות.
שימוש ב-Doxygen על גבי לינוקס
ראשית בואו וניצור 'פרויקט', ניצור קובץ PHP בשם כלשהו (כמו test.php) שיכיל את התוכן הבא:
<?php
/**
* @file
* Test file intended for doxygen testing
* @see https://internet-israel.com
*/
/**
* does nothing
*
* @param teste
* @return null
*/
function foo($foo) {
echo 'hi'.$foo;
return null;
}
מדובר בקובץ פשוט ביותר שמכיל הערות לפי תקן Doxygen, אני אסביר יותר מאוחר מה הן. כרגע תקבלו את זה As-Is.
יצירת קובץ הגדרות
אחרי שיצרנו את 'הפרויקט', עלינו ליצור קובץ הגדרות. כיצד יוצרים קובץ שכזה? מאד פשוט, באותה תיקיה שבה נמצא הקובץ אנו נכתוב:
doxygen -g
אנו יכולים לפרט את שם הקובץ, אבל כרגע לא. מיד נוצר קובץ בשם Doxyfile שמכיל את כל ההגדרות שלנו. אפשר לפתוח את הקובץ ולהסתכל על הגדרות. יש מיליון הגדרות ולכל אחת מהן יש הסבר. כך למשל אנו יכולים לפרט את שם הפרויקט והסברים נוספים, לציין אם אנו רוצים רקורסיה (צלילה אל תוך תיקיות בפרויקט) ועוד שאר פיצ'רים מעניינים. אנו בשלב זה לא ניגע בקובץ ההגדרות.
בניית הדוקומנטציה
בניית הדוקומנטציה היא קלה מאד, פשוט לכתוב:
doxygen Doxyfile
ריצה קצרה ותגלו שנוצרו אצלכם שתי תיקיות – html ו-latex, אם תכנסו עם הדפדפן לתיקית html תגלו את הדוקומנטציה! הנה דוגמא לדוקומנטציה שאתם אמורים לקבל.
זה הכל! מאד קל לייצר דוקומנטציה מלאה בהתבסס על ההערות שלכם.
הסבר על פורמט ההערות
ישנם כמה כללים ברורים בנוגע למבנה ההערות שיש לכתוב על מנת שיתאימו למסמך Doxygen, אני אפרט חלק מהם:
שם קובץ
על כל קובץ להכיל את הטקסט הבא על מנת שייקלט לתוך Doxygen:
/**
* @file
* File short name (80 charactars)
*
* Short description
*/
פונקציות
על כל פונקציה להכיל לפחות מינימום של תיאור קצר כאשר נדרש תיעוד של הפרמטרים ושל מה שהיא מחזירה אם יש פרמטרים והיא מחזירה משהו:
/**
* short description
*
* long description
*
* @param object $varname
* Description
*
* @param array $arrname
* Description
*
* @return varname
* Description
*
* @see OtherObject::somemethod()
*
* @ingroup somegroup
*/
ניתן לכתוב see@ עם שמות של פונקציות, מתודות או אובייקטים (ניתן לכלול כמה כאלו) וגם לציין קבוצות שונות.
משתנים וקבועים
מגדירים משתנים וקבועים באופן הבא:
/**
* description
*/
define('MY_CONSTANT', 0);
/**
* description
*
* @see some_function()
*/
global $var;
בתחילה קשה להתרגל ולכתוב את כל המגילות האלו ליד כל פונקציה, אך בטווח הארוך מדובר באחת הטובות הכי גדולות שתעשו לעצמכם בדרך להיות מתכנתים יותר טובים.
