Skip to main content

Comment and Documentation in Python

Comments and documentation are crucial parts of writing clean and maintainable code in Python. They help explain what the code does, why certain decisions were made, and how to use different parts of the code. Here’s a detailed overview:

1. Single-Line Comments

Single-line comments in Python start with the # symbol. Everything following # on that line is considered a comment.


2. Multi-Line Comments

Multi-line comments can be created by consecutive single-line comments or by using triple quotes (''' or """). Although triple quotes are technically multi-line strings, they are often used for comments.

Consecutive Single-Line Comments:


Triple Quotes:


3. Documentation Strings (Docstrings)

Docstrings are special strings used to document modules, classes, functions, and methods. They are written using triple quotes and can be accessed using the __doc__ attribute.

Module Docstring:

Place the docstring at the top of the module.


Function Docstring:

Place the docstring at the beginning of the function.


Class Docstring:

Place the docstring at the beginning of the class.


4. Inline Comments

Inline comments are used to explain a specific part of a line of code. They are placed on the same line, separated by at least two spaces from the code.


Best Practices for Comments and Documentation

  1. Keep Comments Relevant and Up-to-Date: Ensure comments accurately describe what the code does. Outdated comments can be misleading.
  2. Avoid Redundant Comments: Don’t state the obvious. Comments should provide additional context that isn’t immediately clear from the code itself.
  3. Use Docstrings for Documentation: Use docstrings for documenting modules, classes, functions, and methods. This helps in generating documentation automatically using tools like Sphinx.
  4. Write Clear and Concise Comments: Comments should be clear, concise, and written in proper English. Use complete sentences and proper grammar.
  5. Follow PEP 257: Follow the PEP 257 conventions for writing docstrings, which include recommendations on docstring formatting and style.
This module includes a module-level docstring, function docstrings, and inline comments where necessary, making the code easy to understand and maintain.

Comments

Post a Comment

Popular posts from this blog

Power BI tenant settings and admin portal

As of my last update, Power BI offers a dedicated admin portal for managing settings and configurations at the tenant level. Here's an overview of Power BI tenant settings and the admin portal: 1. Power BI Admin Portal: Access : The Power BI admin portal is accessible to users with admin privileges in the Power BI service. URL : You can access the admin portal at https://app.powerbi.com/admin-portal . 2. Tenant Settings: General Settings : Configure general settings such as tenant name, regional settings, and language settings. Tenant Administration : Manage user licenses, permissions, and access rights for Power BI within the organization. Usage Metrics : View usage metrics and reports to understand how Power BI is being used across the organization. Service Health : Monitor the health status of the Power BI service and receive notifications about service incidents and outages. Audit Logs : Access audit logs to track user activities, access requests, and administrative actions wit...
Post a Comment
Read more

Using bookmarks and buttons for navigation

Using bookmarks and buttons for navigation in Power BI allows you to create interactive experiences within your reports, guiding users through different views and sections. Let's walk through how to use bookmarks and buttons for navigation: Step 1: Create Bookmarks Navigate to the "View" tab : Open your report in Power BI Desktop and navigate to the "View" tab. Create Bookmarks : Select the elements (visuals, slicers, shapes, etc.) that you want to bookmark. Click on the "Bookmark" button in the "View" tab or right-click and select "Add bookmark". Name your bookmark and ensure the "Data" and "Display" options are selected if you want to capture filter states and visual display states. Repeat for Additional Views : Create bookmarks for each view or section of your report that you want to navigate to. Step 2: Create Buttons Insert Buttons : Go to the "Home" tab and click on the "Buttons" dropdow...
Post a Comment
Read more

Performance Optimization

Performance optimization in SQL is crucial for ensuring that your database queries run efficiently, especially as the size and complexity of your data grow. Here are several strategies and techniques to optimize SQL performance: Indexing Create Indexes : Primary Key and Unique Indexes : These are automatically indexed. Ensure that your tables have primary keys and unique constraints where applicable. Foreign Keys : Index foreign key columns to speed up join operations. Composite Indexes : Use these when queries filter on multiple columns. The order of columns in the index should match the order in the query conditions. Avoid Over-Indexing:  Too many indexes can slow down write operations (INSERT, UPDATE, DELETE). Only index columns that are frequently used in WHERE clauses, JOIN conditions, and as sorting keys. Query Optimization Use SELECT Statements Efficiently : SELECT Only Necessary Columns : Avoid using SELECT * ; specify only ...
Post a Comment
Read more