{"title":"Comments","description":"","content":"Code gets read more often than it gets written, and the next person reading yours is usually you, six months later. Comments and docstrings are how Python lets you leave notes for that future reader. This lesson covers the two forms Python supports, when each one is appropriate, and the small set of conventions that keep them useful instead of noisy.\n\n---\n\n# Single-Line Comments with `#`\n\nAnything from a `#` to the end of the line is a comment. Python's parser skips it entirely, so it has zero effect on what the program does.\n\n\n```python\n# Apply a 10 percent discount for orders over \nprice = 89.99\ndiscount = 0.10\nfinal_price = price * (1 - discount)\nprint(final_price)\n```\n\n\nThe `#` can also appear partway through a line. Everything before it runs as code, everything after it is ignored.\n\n\n```python\nquantity = 3 # number of items the customer is buying\nunit_price = 19.99 # price per item in USD\ntotal = quantity * unit_price\nprint(total)\n```\n\n\nBoth styles are valid. A comment on its own line usually explains the block of code that follows it. An inline comment annotates a single line, often a variable whose meaning isn't obvious from its name.\n\nA small style detail worth getting right early: PEP 8, the official Python style guide, recommends two spaces between code and the `#` of an inline comment, then one space after the `#`. So `total = 0 # running cart total`, not `total = 0 #running cart total`. Most editors and formatters apply this automatically.\n\n---\n\n# Python Has No Multi-Line Comment Syntax\n\nIf you've used C, Java, or JavaScript, you've seen `/* ... */` for block comments that span multiple lines. Python doesn't have anything equivalent. The official way to write a multi-line comment is to start each line with its own `#`.\n\n\n```python\n# Calculate the cart total in three steps:\n# 1. Multiply each item's price by its quantity.\n# 2. Sum the subtotals.\n# 3. Apply any active discount on the running total.\nsubtotal = 19.99 * 3\nprint(subtotal)\n```\n\n\nYou will occasionally see people use a triple-quoted string for the same effect:\n\n\n```python\n\"\"\"\nCalculate the cart total in three steps:\n1. Multiply each item's price by its quantity.\n2. Sum the subtotals.\n3. Apply any active discount on the running total.\n\"\"\"\nsubtotal = 19.99 * 3\nprint(subtotal)\n```\n\n\nThat works in the sense that nothing crashes, but it isn't a comment. It's a string literal that gets created and immediately thrown away. The parser still has to read it, and tools that inspect your code will treat it as a string, not a comment. The only place a triple-quoted string has special meaning is as a docstring. Elsewhere, use `#`.\n\n\n> **INFO**\n>\n> **Cost:** A stray triple-quoted \"comment\" allocates a string object every time it appears in module-level code. It's a tiny cost, but it's a real one, and it muddies tooling that scans for docstrings. Stick to `#` for ordinary comments.\n\n\n---\n\n# Triple-Quoted Strings and Docstrings\n\nPython uses triple quotes (`\"\"\"...\"\"\"` or `'''...'''`) for strings that span multiple lines. A normal string literal looks like `\"hello\"`. A triple-quoted one can include line breaks inside it without any escaping:\n\n\n```python\nmessage = \"\"\"Welcome to MyShop.\nYour order has been confirmed.\nEstimated delivery: 3 to 5 business days.\"\"\"\nprint(message)\n```\n\n\nThat's just a regular string. It happens to span three lines.\n\nA **docstring** is what you get when a triple-quoted string sits at the very top of a module, class, or function. Python treats that string as documentation for the object and attaches it to the object's `__doc__` attribute. The built-in `help()` function reads it.\n\n\n```python\ndef apply_discount(price, percent):\n \"\"\"Return the price after applying a percent discount.\"\"\"\n return price * (1 - percent / 100)\n\nprint(apply_discount.__doc__)\n```\n\n\nThree things make that string a docstring rather than a regular string:\n\n1. It uses triple quotes.\n2. It's the first statement of the function body (no code before it).\n3. It's a bare string with no assignment, no `print`, nothing else around it.\n\nMove it anywhere else inside the function, and it becomes a useless string literal that Python evaluates and discards. The placement matters.\n\n---\n\n# Where Docstrings Live\n\nA docstring can sit at the top of three places:\n\n\n| Location | What it documents |\n| --- | --- |\n| Top of a `.py` file | The module |\n| First line inside a `class` body | The class |\n| First line inside a `def` body | The function or method |\n\n\nHere's a module docstring at the top of a file (`cart_utils.py`):\n\n\n```python\n\"\"\"Helpers for building and pricing shopping carts.\n\nThis module contains small functions used across the order pipeline,\nincluding total calculation, tax application, and discount handling.\n\"\"\"\n\ndef cart_total(prices):\n \"\"\"Return the sum of all item prices in the cart.\"\"\"\n return sum(prices)\n```\n\n\nA class docstring sits right under the `class` line:\n\n\n```python\nclass Product:\n \"\"\"A single product in the catalog, with a name and a price.\"\"\"\n\n def __init__(self, name, price):\n self.name = name\n self.price = price\n```\n\n\nAnd a function docstring sits right under the `def` line:\n\n\n```python\ndef is_in_stock(quantity):\n \"\"\"Return True if the quantity is greater than zero.\"\"\"\n return quantity > 0\n```\n\n\nIn each case, the docstring is the first statement of the body. Nothing else can come before it, not even a blank line of code.\n\n---\n\n# Accessing Docstrings: `__doc__` and `help()`\n\nEvery module, class, and function in Python has a `__doc__` attribute. If you wrote a docstring, that's what's stored there. If you didn't, it's `None`.\n\n\n```python\ndef cart_total(prices):\n \"\"\"Return the sum of all item prices in the cart.\"\"\"\n return sum(prices)\n\ndef shipping_fee(weight):\n return 5.00 if weight < 1 else 9.00\n\nprint(cart_total.__doc__)\nprint(shipping_fee.__doc__)\n```\n\n\n`cart_total` has a docstring, so `__doc__` returns the string. `shipping_fee` doesn't, so `__doc__` is `None`. The function still works fine, it just has no documentation attached.\n\nThe `help()` built-in does something similar but prints a more readable view. In a REPL session:\n\n\n```python\n>>> def cart_total(prices):\n... \"\"\"Return the sum of all item prices in the cart.\"\"\"\n... return sum(prices)\n...\n>>> help(cart_total)\nHelp on function cart_total in module __main__:\n\ncart_total(prices)\n Return the sum of all item prices in the cart.\n```\n\n\n`help()` shows the function's signature on one line and the docstring underneath. It works the same way on classes and modules. This is the same machinery that powers the documentation in IDEs, hover tooltips, and Jupyter's `?` shortcut. Write a docstring, and your editor knows what your function does.\n\n---\n\n# PEP 257: The Short Version\n\nPEP 257 is the official convention for writing docstrings. It's short, and the rules that matter for everyday code fit in a few bullet points:\n\n- Use triple double quotes (`\"\"\"...\"\"\"`), even when the docstring fits on one line. Triple single quotes work too, but the convention is double.\n- For a one-line docstring, keep the opening and closing quotes on the same line: `\"\"\"Return the sum of cart prices.\"\"\"`.\n- Write the summary as an imperative sentence: `\"Return the total\"`, not `\"Returns the total\"` or `\"This function returns the total\"`. Think of it as a command to the function.\n- End the summary with a period, even if it's just a phrase.\n- For a multi-line docstring, put the summary on the first line, leave a blank line, then add the longer description.\n\nA one-line docstring:\n\n\n```python\ndef cart_total(prices):\n \"\"\"Return the sum of all item prices in the cart.\"\"\"\n return sum(prices)\n```\n\n\nA multi-line docstring:\n\n\n```python\ndef apply_discount(price, percent):\n \"\"\"Return the price after applying a percent discount.\n\n The percent is given as a number between 0 and 100. A percent of 0\n leaves the price unchanged, and a percent of 100 returns 0.0.\n \"\"\"\n return price * (1 - percent / 100)\n```\n\n\nNotice that the closing `\"\"\"` of a multi-line docstring goes on its own line. That's a small detail PEP 257 calls out specifically.\n\nDetailed conventions for documenting parameters and return values (the `Args:`, `Returns:`, `Raises:` blocks you may have seen in larger codebases) are part of writing function docstrings well. For now, a clear summary sentence is enough.\n\n---\n\n# When to Comment: Explain the Why, Not the What\n\nThe hardest part of writing good comments is knowing when not to write them. A comment that restates what the code already says adds noise. A comment that explains why the code exists adds real information.\n\nHere's a comment that adds nothing:\n\n\n```python\n# Increment count by 1\ncount = count + 1\n```\n\n\nThe code already says that. Anyone reading it can see what's happening. The comment makes the line longer without telling them anything new.\n\nHere's a comment that pulls its weight:\n\n\n```python\n# Free shipping kicks in at to push customers\n# toward a higher cart value instead of bouncing at checkout.\nfree_shipping_threshold = 50.00\n```\n\n\nNow the reader knows why this specific number is in the code. If a product manager later asks to change it, the next developer understands the reasoning behind the original choice. That's information you can't get from the variable name alone.\n\nThe same principle applies to a non-obvious calculation:\n\n\n```python\n# Apply tax before the discount because state law treats the discount\n# as a price reduction, not as an exemption from tax.\ntax = subtotal * 0.0725\ntotal = (subtotal + tax) * (1 - discount_percent / 100)\n```\n\n\nWithout the comment, the next developer might \"fix\" the order by applying the discount first, which would silently change every total in the system. The comment defends the code from well-intentioned changes.\n\nA useful test before adding a comment: \"If I rename the variables and clean up the code, does this comment still need to exist?\" If clearer code would erase the need for the comment, write the clearer code first. Comments are a backup, not a substitute for readable code.\n\n---\n\n# Avoid Commented-Out Dead Code\n\nThis is one of the most common comment anti-patterns:\n\n\n```python\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n # return price - (price * percent / 100)\n # return price * (100 - percent) / 100\n```\n\n\nThree older versions of the same calculation, all commented out. Each was probably correct once. Now they just sit there, taking up space and forcing the reader to wonder whether one of them is the \"real\" version that should be uncommented.\n\nCommented-out code rots fast. The function signature changes, the variable names drift, the logic moves to a new file, and the commented version no longer matches reality. It becomes a lie the reader has to mentally filter out.\n\nThe fix is simple: delete it. Your version control system (Git, for example) remembers every line you ever wrote. If you need the old version back, the history has it. The current file should only contain the code that's actually running.\n\nIf a chunk of code is genuinely temporary (a feature flag, an experiment you'll re-enable next week), use a real mechanism for it: a variable, a function parameter, a configuration value. Don't park it in a comment and hope nobody touches it.\n\n\n```mermaid\nflowchart LR\n A[Old code
you might need]:::orange --> B{Will you need
it again soon?}:::cyan\n B -->|No| C[Delete it
Git has history]:::green\n B -->|Yes, but later| D[Move to a branch
or feature flag]:::teal\n B -->|Right now| E[Keep it active
with a flag]:::red\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe flow above is the decision you make every time you're tempted to leave a block of code commented out. The default answer is to delete.\n\n---\n\n# Putting It Together\n\nHere's a small module that uses all of the pieces this lesson covers: a module docstring, function docstrings, a useful inline comment, and zero dead code.\n\n\n```python\n\"\"\"Tiny helpers for an order summary in a shopping cart demo.\n\nThe functions in this module assume prices are floats in USD and that\nquantities are whole numbers.\n\"\"\"\n\ndef line_total(price, quantity):\n \"\"\"Return the price for a single line on the order.\"\"\"\n return price * quantity\n\ndef apply_discount(amount, percent):\n \"\"\"Return the amount after applying a percent discount.\n\n The percent is given as a number between 0 and 100. A percent of 0\n leaves the amount unchanged.\n \"\"\"\n # Convert percent to a fraction so 10 becomes 0.10.\n return amount * (1 - percent / 100)\n\nsubtotal = line_total(19.99, 3)\nfinal = apply_discount(subtotal, 10)\nprint(round(final, 2))\n```\n\n\nEvery docstring is a one-line or short multi-line summary in the imperative mood. The inline comment explains a small conversion that isn't obvious at a glance. There's no commented-out code. The module docstring tells a new reader what this file is for before they read a single line of logic.\n\n---\n\n# Quiz","pageType":"python"}

Get Premium