Skip to main content

What are the guidelines for adding comments in source code? When is it necessary to include comments?

Adding comments to source code is an important part of writing clean, maintainable, and understandable code. Here are the guidelines and when it’s necessary to include them:

What are the guidelines for adding comments in source code? When is it necessary to include comments?

✅ Guidelines for Adding Comments

  1. Be Clear and Concise Keep comments short but informative. Use complete sentences if needed, but avoid rambling.
  2. Explain "Why", Not Just "What" Good code explains what is happening. Comments should explain why it’s happening—especially for non-obvious logic or design decisions.
  3. Avoid Redundant Comments # Increment i by 1 i = i + 1 # <- This is obvious and unnecessary Instead, only comment when the code’s purpose isn't immediately clear.
  4. Use Proper Grammar and Punctuation Especially in team environments—treat comments like documentation.
  5. Keep Comments Up to Date Outdated comments can be worse than no comments at all.
  6. Use TODOs and FIXMEs Sparingly Clearly tag work that needs to be done. Example: # TODO: Refactor this loop to improve performance
  7. Comment Code Blocks, Not Every Line Avoid cluttering the code; summarize what a block does instead of annotating every line.
  8. Use Docstrings for Functions and Classes Especially for public APIs or anything reused. pythonCopyEditdef add(a, b): """Return the sum of a and b.""" return a + b
  9. Stick to a Consistent Style Follow your team’s or language’s style guide (e.g., PEP 8 for Python, Javadoc for Java, etc.).

🟡 When It’s Necessary to Include Comments

  • Complex or Tricky Code If the logic is clever or non-intuitive, explain it.
  • Workarounds or Hacks Mention why a workaround was necessary and what limitation it's addressing.
  • External Dependencies Note where the code relies on third-party behavior or versions.
  • Business Logic Explain decisions that stem from business rules, especially if they might change.
  • Assumptions If your code depends on specific assumptions, document them.
  • Interfaces and APIs Always comment public methods, expected parameters, return types, and side effects.   

 

Popular posts from this blog

How does BGP prevent routing loops? Explain AS_PATH and loop prevention mechanisms.

 In Border Gateway Protocol (BGP), preventing routing loops is critical — especially because BGP is the inter-domain routing protocol used to connect Autonomous Systems (ASes) on the internet. 🔄 How BGP Prevents Routing Loops The main mechanism BGP uses is the AS_PATH attribute . 🔍 What is AS_PATH? AS_PATH is a BGP path attribute that lists the sequence of Autonomous Systems (AS numbers) a route has traversed. Each time a route is advertised across an AS boundary, the local AS number is prepended to the AS_PATH. Example: If AS 65001 → AS 65002 → AS 65003 is the route a prefix has taken, the AS_PATH will look like: makefile AS_PATH: 65003 65002 65001 It’s prepended in reverse order — so the last AS is first . 🚫 Loop Prevention Using AS_PATH ✅ Core Mechanism: BGP routers reject any route advertisement that contains their own AS number in the AS_PATH. 🔁 Why It Works: If a route makes its way back to an AS that’s already in the AS_PATH , that AS kno...
Read more

Explain the Angular compilation process: View Engine vs. Ivy.

 The Angular compilation process transforms your Angular templates and components into efficient JavaScript code that the browser can execute. Over time, Angular has evolved from the View Engine compiler to a newer, more efficient system called Ivy . Here's a breakdown of the differences between View Engine and Ivy , and how each affects the compilation process: 🔧 1. What Is Angular Compilation? Angular templates ( HTML inside components) are not regular HTML—they include Angular-specific syntax like *ngIf , {{ }} interpolation, and custom directives. The compiler translates these templates into JavaScript instructions that render and update the DOM. Angular uses Ahead-of-Time (AOT) or Just-in-Time (JIT) compilation modes: JIT : Compiles in the browser at runtime (used in development). AOT : Compiles at build time into efficient JS (used in production). 🧱 2. View Engine (Legacy Compiler) ➤ Used in Angular versions < 9 🔍 How It Works: Compiles templat...
Read more

What are the different types of directives in Angular? Give real-world examples.

In Angular, directives are classes that allow you to manipulate the DOM or component behavior . There are three main types of directives: 🧱 1. Component Directives Technically, components are directives with a template. They control a section of the screen (UI) and encapsulate logi c. ✅ Example: @Component ({ selector : 'app-user-card' , template : `<h2>{{ name }}</h2>` }) export class UserCardComponent { name = 'Alice' ; } 📌 Real-World Use: A ProductCardComponent showing product details on an e-commerce site. A ChatMessageComponent displaying individual messages in a chat app. ⚙️ 2. Structural Directives These change the DOM layout by adding or removing elements. ✅ Built-in Examples: *ngIf : Conditionally includes a template. *ngFor : Iterates over a list and renders template for each item. *ngSwitch : Switches views based on a condition. 📌 Real-World Use: < div * ngIf = "user.isLoggedIn...
Read more