Programming - Python

Comments vs. Docstrings – The Art of Communication in Python

Published: February 8, 2026 | Category: Programming

In programming, we often say that "code is read much more often than it is written." However, many developers either over-comment every line or leave their code in total silence. Today, let’s clear up the confusion between simple comments and professional documentation in Python.

Inline Comments (#) – Explaining the "Why"

The hash symbol is your tool for quick notes. The golden rule? Don't use comments to explain WHAT the code is doing—the code should be clear enough for that. Use them to explain WHY you did it.

❌ Bad Practice:

price = price * 1.10  # Multiply price by 1.10 

# Standard VAT rate applied as per 2026 regulations

Multi-line Strings: The """ """ Myth

You’ve probably seen blocks of text wrapped in triple quotes. Here’s a quick tip:
Python doesn't actually have a dedicated multi-line comment syntax.

Technically, these are just strings that aren't assigned to any variable. While they are great for "commenting out" large chunks of code during testing, they should be used primarily as Docstrings in finished projects.

Docstrings – Your Professional Signature

This is where you move from "coder" to "engineer." A Docstring is a string literal that occurs as the very first statement in a module, function, class, or method definition.
Why use them? Because Python’s internal engine recognizes them. You can access them using the help() function or by calling the __doc__ attribute.

Example of Professional Documentation:

def calculate_margin(net_price, tax=0.10):
    """
    Calculates the gross price for projects at Kajotte Studio.

    Args:
        net_price (float): The base project cost.
        tax (float): VAT rate (defaults to 0.10).

    Returns:
        float: Final price rounded to two decimal places.
    """
    return round(net_price * (1 + tax), 2)

Why Does This Matter for Your Projects?

Summary for the Developer:

1.   Use # for brief logic explanations (the "Why").
2.   Use """ """ as Docstrings to define the purpose and parameters of your functions.
3.   Clean Code First: If your code needs a comment to be understood, consider renaming your variables first!

To generate a professional HTML documentation site, we use the pdoc library.

For engineers and developers aiming for full workflow automation, the following reference module implements documentation standards recognized by modern tools like Sphinx or pdoc. Utilizing a consistent format (Google Style) enables the generation of clear technical manuals directly from the source code, which is critical for project scalability and maintaining high software quality.

Documentation Template for Copy-Paste (MIT License):

Installation (run once only)

pip install pdoc

pip install pdoc && pdoc post_42en.py -o ./docs

Generating documentation:

pdoc post_42en.py -o ./docs

Note: The command above creates a docs folder in your project directory. To view the result, navigate to that folder and open the post_42pl.html file in any web browser. If you prefer to launch a local live-preview server immediately, use:

pdoc post_42en.py

In-Code Documentation: The Power of the help() Function and Docstrings

Published: May 12, 2026 | Category: Programming

In the professional software development process, documentation is not a mere addition but an integral part of the codebase. One of the most effective ways to maintain high project readability is to leverage Python's built-in mechanisms: docstrings and the help() function.

1. The help() Function – Interactive Developer Support

The help() function is a built-in introspection tool designed to generate and display object documentation interactively. It allows for an immediate overview of the structure of modules, classes, or functions without the need to leave the development environment.

2. Implementation in the SAKS System

As part of the Kajotte Studio project—specifically within the SAKS (System Autostart Kajotte Studio) module—this mechanism has been utilized to create an autonomous information system. Instead of relying on external text files, key information regarding versions, modification dates, and script intent is embedded directly into the source code.

The following example illustrates how to force the display of documentation during module initialization:

def docinfo_index_html():
    """
    Kajotte Studio Autostart System
    SAKS Module: 2026-05-12
    Status: Active
    Description: Script responsible for generating the index.html structure.
    """
    pass

# Displaying documentation in the console upon execution
print(help(docinfo_index_html))

3. Underlying Mechanism and Benefits

The use of triple quotes (""") immediately following a function definition creates what is known as a docstring. Python automatically assigns this text to the object's __doc__ attribute. The help() function invokes this attribute and formats it clearly for the reader.

Advantages of this approach:

This methodology promotes a "Clean Code" culture and builds a knowledge base accessible instantly from the terminal—a vital component in educational and open-source projects.

👇

▒ Blog Guide: All Programming Posts in One Place. ▹ See