ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್‌ಗಳು (Docstrings)

ಪೈಥಾನ್‌ನಲ್ಲಿ, ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ (Docstring) ಎಂದರೆ ಒಂದು ಮೊಡ್ಯೂಲ್, ಫಂಕ್ಷನ್, ಕ್ಲಾಸ್, ಅಥವಾ ಮೆಥಡ್‌ನ ಉದ್ದೇಶವನ್ನು ವಿವರಿಸುವ ಒಂದು ಸ್ಟ್ರಿಂಗ್ ಲಿಟರಲ್. ಇದು ಆಬ್ಜೆಕ್ಟ್‌ನ ಮೊದಲ ಸ್ಟೇಟ್‌ಮೆಂಟ್ ಆಗಿ ಕಾಣಿಸಿಕೊಳ್ಳುತ್ತದೆ.

ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್‌ಗಳು ಕೇವಲ ಕಾಮೆಂಟ್‌ಗಳಲ್ಲ. ಇವುಗಳನ್ನು ಪೈಥಾನ್‌ನ help() ಫಂಕ್ಷನ್ ಮತ್ತು Sphinx ನಂತಹ ಡಾಕ್ಯುಮೆಂಟೇಶನ್ ಜನರೇಟರ್ ಪರಿಕರಗಳು ಬಳಸಿ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ವೆಬ್‌ಸೈಟ್‌ಗಳು ಮತ್ತು ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ರಚಿಸಲು ಬಳಸಲಾಗುತ್ತದೆ.

ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ ಬರೆಯುವುದು ಹೇಗೆ?

ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್‌ಗಳನ್ನು ಟ್ರಿಪಲ್ ಕೋಟ್ಸ್ ("""...""" ಅಥವಾ '''...''') ಬಳಸಿ ಬರೆಯಲಾಗುತ್ತದೆ.

1. ಒಂದು-ಸಾಲಿನ ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ (One-line Docstrings)

ಸಣ್ಣ ಮತ್ತು ಸ್ಪಷ್ಟ ಫಂಕ್ಷನ್‌ಗಳಿಗಾಗಿ ಇದನ್ನು ಬಳಸಲಾಗುತ್ತದೆ. ಇದು ಫಂಕ್ಷನ್ ಏನು ಮಾಡುತ್ತದೆ ಎಂಬುದನ್ನು ಸಂಕ್ಷಿಪ್ತವಾಗಿ ವಿವರಿಸುವ ಒಂದು ಪೂರ್ಣ ವಾಕ್ಯವಾಗಿರಬೇಕು.

def add(a, b):
    """ಎರಡು ಸಂಖ್ಯೆಗಳನ್ನು ಕೂಡಿಸುತ್ತದೆ ಮತ್ತು ಮೊತ್ತವನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ."""
    return a + b

2. ಬಹು-ಸಾಲಿನ ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ (Multi-line Docstrings)

ಸಂಕೀರ್ಣ ಫಂಕ್ಷನ್‌ಗಳು, ಕ್ಲಾಸ್‌ಗಳು, ಮತ್ತು ಮೊಡ್ಯೂಲ್‌ಗಳಿಗಾಗಿ ಇದನ್ನು ಬಳಸಲಾಗುತ್ತದೆ. ಇದು ಈ ಕೆಳಗಿನ ಭಾಗಗಳನ್ನು ಹೊಂದಿರಬಹುದು: 1. ಸಾರಾಂಶ: ಒಂದು-ಸಾಲಿನ ಸಾರಾಂಶ. 2. ಖಾಲಿ ಸಾಲು: ಸಾರಾಂಶದ ನಂತರ ಒಂದು ಖಾಲಿ ಸಾಲು. 3. ವಿವರಣೆ: ಫಂಕ್ಷನ್‌ನ ವಿವರವಾದ ವಿವರಣೆ. 4. ಆರ್ಗ್ಯುಮೆಂಟ್ಸ್: ಪ್ರತಿ ಆರ್ಗ್ಯುಮೆಂಟ್‌ನ ವಿವರಣೆ. 5. ರಿಟರ್ನ್ಸ್: ಫಂಕ್ಷನ್ ಏನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ ಎಂಬುದರ ವಿವರಣೆ. 6. ಎರರ್‌ಗಳು: ಫಂಕ್ಷನ್ ಯಾವ ಎರರ್‌ಗಳನ್ನು ಎಬ್ಬಿಸಬಹುದು ಎಂಬುದರ ವಿವರಣೆ.

ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ ಶೈಲಿಗಳು (Docstring Styles)

ಪೈಥಾನ್ ಸಮುದಾಯದಲ್ಲಿ ಹಲವಾರು ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ ಫಾರ್ಮ್ಯಾಟ್‌ಗಳು ಜನಪ್ರಿಯವಾಗಿವೆ. ಇವುಗಳನ್ನು ಡಾಕ್ಯುಮೆಂಟೇಶನ್ ಜನರೇಟರ್‌ಗಳು ಸುಲಭವಾಗಿ ಪಾರ್ಸ್ ಮಾಡುತ್ತವೆ.

1. Google Style

ಇದು ಓದಲು ಸುಲಭ ಮತ್ತು ಸ್ಪಷ್ಟವಾಗಿದೆ.

def calculate_power(base: int, exponent: int) -> int:
    """ಒಂದು ಸಂಖ್ಯೆಯ ಘಾತವನ್ನು ಲೆಕ್ಕಾಚಾರ ಮಾಡುತ್ತದೆ.

    Args:
        base (int): ಆಧಾರ ಸಂಖ್ಯೆ.
        exponent (int): ಘಾತ ಸಂಖ್ಯೆ.

    Returns:
        int: `base` ನ `exponent` ಘಾತದ ಫಲಿತಾಂಶ.
    """
    return base ** exponent

2. reStructuredText (reST) Style

ಇದು ಪೈಥಾನ್‌ನ ಅಧಿಕೃತ ಡಾಕ್ಯುಮೆಂಟೇಶನ್‌ನಲ್ಲಿ ಮತ್ತು Sphinx ನಲ್ಲಿ ಹೆಚ್ಚಾಗಿ ಬಳಸಲಾಗುವ ಫಾರ್ಮ್ಯಾಟ್ ಆಗಿದೆ.

def calculate_power(base: int, exponent: int) -> int:
    """ಒಂದು ಸಂಖ್ಯೆಯ ಘಾತವನ್ನು ಲೆಕ್ಕಾಚಾರ ಮಾಡುತ್ತದೆ.

    :param base: ಆಧಾರ ಸಂಖ್ಯೆ.
    :type base: int
    :param exponent: ಘಾತ ಸಂಖ್ಯೆ.
    :type exponent: int
    :return: `base` ನ `exponent` ಘಾತದ ಫಲಿತಾಂಶ.
    :rtype: int
    """
    return base ** exponent

3. NumPy/SciPy Style

NumPy, SciPy, ಮತ್ತು ಇತರ ವೈಜ್ಞಾನಿಕ ಪೈಥಾನ್ ಲೈಬ್ರರಿಗಳಲ್ಲಿ ಈ ಶೈಲಿಯನ್ನು ಬಳಸಲಾಗುತ್ತದೆ. ಇದು ಹೆಚ್ಚು ವಿವರವಾಗಿರುತ್ತದೆ.

def calculate_power(base: int, exponent: int) -> int:
    """ಒಂದು ಸಂಖ್ಯೆಯ ಘಾತವನ್ನು ಲೆಕ್ಕಾಚಾರ ಮಾಡುತ್ತದೆ.

    Parameters
    ----------
    base : int
        ಆಧಾರ ಸಂಖ್ಯೆ.
    exponent : int
        ಘಾತ ಸಂಖ್ಯೆ.

    Returns
    -------
    int
        `base` ನ `exponent` ಘಾತದ ಫಲಿತಾಂಶ.
    """
    return base ** exponent

ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ ಅನ್ನು ಪ್ರವೇಶಿಸುವುದು

ಒಂದು ಆಬ್ಜೆಕ್ಟ್‌ನ ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್ ಅನ್ನು ಅದರ __doc__ ಅಟ್ರಿಬ್ಯೂಟ್ ಮೂಲಕ ಅಥವಾ help() ಫಂಕ್ಷನ್ ಬಳಸಿ ಪ್ರವೇಶಿಸಬಹುದು.

def greet(name):
    """ಬಳಕೆದಾರರಿಗೆ ಶುಭಾಶಯ ಕೋರುತ್ತದೆ."""
    print(f"ನಮಸ್ಕಾರ, {name}")

# __doc__ ಬಳಸಿ
print(greet.__doc__)

# help() ಬಳಸಿ
help(greet)

ಉತ್ತಮ ಡಾಕ್ಸ್‌ಸ್ಟ್ರಿಂಗ್‌ಗಳನ್ನು ಬರೆಯುವುದು ನಿಮ್ಮ ಕೋಡ್ ಅನ್ನು ಹೆಚ್ಚು ವೃತ್ತಿಪರ, ನಿರ್ವಹಿಸಬಲ್ಲ, ಮತ್ತು ಇತರರಿಗೆ ಸುಲಭವಾಗಿ ಅರ್ಥವಾಗುವಂತೆ ಮಾಡುತ್ತದೆ.