AJAX + PHP कोड दस्तावेज़ करने का सबसे अच्छा तरीका?

Question

मैं हमेशा कोडिंग दस्तावेज़ के लिए रहा हूं, लेकिन जब यह AJAX + PHP की बात आती है, तो यह हमेशा आसान नहीं होता है: कोड वास्तव में फैल गया है! तर्क, डेटा, प्रस्तुति - आप इसे नाम दें - विभाजित और सर्वर-साइड और क्लाइंट-साइड कोड के बीच मिश्रित हैं। कभी-कभी डेटाबेस के साइड कोड (संग्रहीत प्रक्रियाओं, विचारों, आदि) भी काम का हिस्सा कर रहे हैं।

इससे मुझे ऐसे कोड को दस्तावेज करने के लिए एक प्रभावी तरीके से आने की चुनौती मिलती है। मैं आमतौर पर .jp फ़ाइल के अंदर .js फ़ाइलों की एक सूची प्रदान करता हूं साथ ही .js फ़ाइल के अंदर .php फ़ाइलों की सूची प्रदान करता हूं। मैं इन-लाइन टिप्पणियों और फ़ंक्शन विवरण भी करता हूं, जहां मैं सूचीबद्ध करता हूं कि कौन सी फ़ंक्शन का उपयोग किया जाता है और किस आउटपुट की अपेक्षा की जाती है। मैं डेटाबेस प्रक्रियाओं के लिए समान कार्य करता हूं। शायद एक बेहतर तरीका है?

कोई विचार या अनुभव?

नोट: यह प्रश्न किसी भी क्लाइंट + सर्वर-साइड अनुप्रयोगों पर लागू होता है, न केवल जावास्क्रिप्ट + PHP।

Answer 1

मुझे लगता है कि एक पदानुक्रमित दृष्टिकोण लेना सबसे अच्छा है।

समारोह और वर्ग स्तर पर की तरह एपीआई स्तर के दस्तावेज़ीकरण के लिए, कोड में इनलाइन प्रलेखन लिख सकते हैं और उनमें से बाहर एचटीएमएल प्रलेखन उत्पन्न वहाँ (JSDoc, phpDocumentor, OraDoclet, आदि) कई प्रलेखन उपकरण का उपयोग कर। बोनस पॉइंट्स यदि आपके दस्तावेज़ टूल आपके स्रोत नियंत्रण टूल के साथ एकीकृत कर सकते हैं ताकि आप अपने एपीआई दस्तावेज़ों से कोड की विशिष्ट पंक्तियों पर जा सकें।

एक बार जब आपके पास आपके दस्तावेज़ उपकरण होते हैं, तो प्रत्येक नई बिल्ड के लिए अपनी बिल्ड प्रक्रिया (आपके पास एक बिल्ड प्रक्रिया है, है ना?) के रूप में प्रलेखन उत्पन्न करना शुरू करें और दस्तावेज़ को मानक वेब स्थान पर दबाएं।

एक बार ये एपीआई दस्तावेज़ ऑनलाइन होने के बाद, आप ब्राउज़र-> वेब-> डीबी इंटरैक्शन, उपयोगकर्ता कहानियां, स्कीमा आरेख आदि जैसे उच्च स्तरीय दस्तावेज़ों के लिए विकी बना सकते हैं। संक्षिप्त गद्य या बुलेट पॉइंट्स में लिखना सर्वोत्तम है उच्च स्तर के दस्तावेज़ीकरण, जब आवश्यक हो तो एपीआई दस्तावेज़ों और स्रोत नियंत्रण से लिंक करना।

Answer 2

मुझे लगता है कि आपकी विधि बहुत अच्छी है। केवल एक चीज यह है कि जेएस फ़ाइल के अंदर सबकुछ दूसरों द्वारा पठनीय है और इसलिए दस्तावेज है कि PHP फाइलों का उपयोग किस प्रकार किया जा सकता है, एक सुरक्षा छेद का कारण बन सकता है, ऑफ मौके पर वे एक फ़ाइल में जा सकते हैं जो कुछ ऐसा नहीं करता है। इसके अलावा, हालांकि, एक बड़ा सौदा नहीं है, उच्च ट्रैफिक साइटों पर, डाउनलोड करने से 500bytes टिप्पणियां जोड़ सकती हैं।

इनमें से दोनों बड़े नहीं हैं, लेकिन केवल विचार जो मैंने पहले किया था।

Answer 3

PHP के माध्यम से अपने जावास्क्रिप्ट (और सीएसएस) की सेवा करें - आप आसानी से क्रॉस संदर्भ के लिए अपनी स्रोत फ़ाइलों को एक साथ रख सकते हैं और हेडर के सावधानीपूर्वक उपयोग के साथ आप आसानी से कैशिंग को संभाल सकते हैं। ऐसा करने से आपको एक अच्छी तरह से स्वरूपित टिप्पणी-भारी स्रोत संस्करण मिल सकता है जिसे आप ब्राउज़र पर भेजने से पहले कंडेन या obfuscate कर सकते हैं।

function OutputJs($Content) { 
    ob_start(); 
    echo $Content; 
    $expires = DAY_IN_S; 
    header("Content-type: x-javascript"); 
    header('Content-Length: ' . ob_get_length()); 
    header('Cache-Control: max-age='.$expires.', must-revalidate'); 
    header('Pragma: public'); 
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT'); 
    ob_end_flush(); 
} 

Answer 4

जावास्क्रिप्ट का एक बहुत साथ परियोजनाओं के लिए, मैं एक निर्माण प्रणाली (makefiles) एक javascript minimizer साथ उपयोग करें। जैसा कि जेएसआईएम लेखक नोट करते हैं, टिप्पणियों को अलग करना "एक अधिक अभिव्यक्तिपूर्ण प्रोग्रामिंग शैली को प्रोत्साहित करता है क्योंकि यह स्वच्छ, साक्षर स्वयं-दस्तावेज की डाउनलोड लागत को समाप्त करता है।"

बोनस यह है कि जेएसआईएन सीएसएस से टिप्पणियां भी दबाता है - ताकि आप वहां भी स्वतंत्र रूप से टिप्पणी करना शुरू कर सकें। (मुझे लगता है कि स्पष्ट जावास्क्रिप्ट लिखने के लिए सीएसएस कक्षाओं का उपयोग करना महत्वपूर्ण है।)

डायनामिक रूप से कोड को बाहर निकालने और जावास्क्रिप्ट फ़ाइलों को व्यवस्थित करने के लिए PHP का उपयोग करना एक दिलचस्प विचार है।ध्यान रखें कि वेब ऐप्स के लिए एक महत्वपूर्ण अनुकूलन reduce HTTP requests है इसलिए छोटे जावास्क्रिप्ट फ़ाइलों को एक साथ जोड़ना अक्सर बुद्धिमान होता है। (मैंने पाया है कि कम से कम एक फ़ाइल में कम से कम जेएस फाइलों को संयोजित करना, बहुत अच्छा काम करता है।)