Comments in C++

Comment क्या है?

Comment source code में लिखा वह text है जिसे compiler अनदेखा करता है। यह इंसानों के लिए होता है — आपके teacher, साथी, या छह महीने बाद खुद आपके लिए — ताकि समझ आए कि code किस लिए है और ऐसा क्यों लिखा गया है। Compilation से पहले preprocessor सारे comments हटा देता है, इसलिए comments program के चलने पर कोई असर नहीं डालते।

Single-line comments: //

// से लेकर उस line के अंत तक सब कुछ comment होता है। यह अपनी अलग line पर भी हो सकता है और किसी statement के बाद भी।

#include <iostream>

int main() {
    // Class के लिए welcome message print करो
    std::cout << "Welcome to C++!\n";

    int passMarks = 33;   // CBSE का न्यूनतम pass प्रतिशत
    std::cout << "Pass marks: " << passMarks << "\n";
    return 0;
}

Modern C++ code में single-line comments सबसे ज़्यादा इस्तेमाल होते हैं।

Multi-line (block) comments: /* ... */

/* और */ के बीच का text comment होता है, चाहे कितनी भी lines में फैला हो। File या function के ऊपर लंबा विवरण लिखने में यह काम आता है।

/*
   Program : Student result calculator
   Author  : Aman, Class XII-A
   Purpose : 5 subjects के marks पढ़कर
             total, percentage और grade print करता है।
*/
#include <iostream>
int main() {
    int total = 0; /* marks का चलता हुआ total */
    return 0;
}

Block comment line के बीच में भी आ सकता है, जैसे int x = /* default */ 10;, पर यह style शायद ही कभी अच्छा होता है।

Block comments nest नहीं होते

पहला */ हमेशा comment बंद कर देता है। यह बहुत आम गलती है:

/*  पुराना code, अभी बंद है
    int a = 5;  /* temporary value */
    int b = 7;
*/

Comment temporary value */ के बाद ही ख़त्म हो जाता है, इसलिए int b = 7; चालू code बन जाता है और आख़िरी */ syntax error देता है। जिस बड़े block में पहले से comments हों, उसे बंद करने के लिए preprocessor इस्तेमाल करें:

#if 0
    int a = 5;  /* temporary value */
    int b = 7;
#endif

Documentation comments

Doxygen जैसे tools खास format वाले comments से HTML documentation बना सकते हैं। ये साधारण comments ही हैं जो /** या /// से शुरू होते हैं और @param, @return जैसे tags लेते हैं।

/**
 * प्राप्त marks का percentage निकालता है।
 * @param obtained student के प्राप्त marks
 * @param maximum  exam के कुल marks (0 से बड़ा होना चाहिए)
 * @return 0 से 100 के बीच integer percentage
 */
int percentage(int obtained, int maximum) {
    return obtained * 100 / maximum;
}

Doxygen कभी न चलाएँ तब भी यह layout साफ़ बता देता है कि function कैसे इस्तेमाल करना है।

अच्छा comment कैसा होता है?

और tips:

• पहले साफ़ नाम रखें; comment तभी जोड़ें जब नाम पूरी बात न कह सके।
• Comments को update रखें — पुराना गलत comment, comment न होने से भी बुरा है।
• Exams और practical file में छोटा header comment (program का नाम, उद्देश्य) और हर logical step पर एक comment सबसे अच्छा है।

Debugging में comments का इस्तेमाल

किसी line को "comment out" करना यह जाँचने का तेज़ तरीका है कि problem उसी से है या नहीं:

// std::cout << "debug: total = " << total << "\n";

Code submit या share करने से पहले ऐसी lines हटा दें — बचा हुआ commented-out code पढ़ने वालों को उलझाता है।

आम गलतियाँ

• /* */ comments को nest करना, जैसा ऊपर दिखाया।
• Block comment बंद करना भूल जाना — बाकी पूरी file चुपचाप comment बन जाती है और "expected ... at end of input" जैसी उलझी errors आती हैं।
• // की जगह / लिखना, जिसे compiler भाग (division) समझता है।
• हर साफ़ line पर comment लिखना, जिससे ज़रूरी comments छिप जाते हैं।
• पुराना code delete करने की जगह comment करके छोड़ देना।

सारांश

• // comment line के अंत तक चलता है; /* */ comment कई lines में फैल सकता है।
• Compilation से पहले comments हट जाते हैं, speed पर कोई असर नहीं।
• Block comments nest नहीं होते — बड़े blocks बंद करने के लिए #if 0 ... #endif लें।
• /** */ और /// doc comments से Doxygen documentation बना सकता है।
• "क्यों" पर comment करें, comments update रखें, और बेकार code हटा दें।

संबंधित: C++ program की संरचना, preprocessor directives, C++ best practices।