Recently, I was working on a large TypeScript project with my team. Since many of us were working on the same codebase, some teammates struggled to understand parts of the logic.
This highlighted the importance of clear comments for seamless team collaboration. By adding simple, clear comments above complex code and using TODO notes where updates are required, we can help everyone understand the code more quickly and avoid confusion in future updates.
In this article, I’ll cover several methods to effectively use comments in TypeScript that I’ve refined over my six years of experience with the language.
Single-Line Comments in TypeScript
Single-line comments are perfect for brief explanations and are the most common type you’ll use in your TypeScript projects.
Here’s how to use them:
// This is a single-line comment
const userAge: number = 35; // This declares the user's ageSingle-line comments start with // and continue until the end of the line. I often use them for quick explanations about a variable or to disable a line of code during debugging temporarily.
Check out: Create Custom Error Types in TypeScript
Multi-Line Comments in TypeScript
When you need to write longer explanations or temporarily comment out blocks of code, multi-line comments are your best friend.
/* This is a multi-line comment
that spans several lines.
Perfect for longer explanations.
*/
const calculateTax = (income: number): number => {
/* As per 2023 US tax regulations,
we apply a progressive tax rate
for different income brackets */
return income * 0.22; // Simplified for example
};Multi-line comments start with /* and end with */. Everything between these markers is treated as a comment, regardless of the number of lines it spans.
Check out: Property Does Not Exist on Type Error in TypeScript
JSDoc Comments in TypeScript for Better Documentation
If you’re serious about code documentation, JSDoc comments are a game-changer in TypeScript.
/**
* Calculates federal income tax based on filing status and income
* @param income The total taxable income in USD
* @param filingStatus The tax filing status (single, married, etc.)
* @returns The calculated tax amount in USD
*/
function calculateFederalTax(income: number, filingStatus: FilingStatus): number {
// Implementation here
return taxAmount;
}JSDoc comments start with /** and end with */. They support special tags like @param, @returns, and many others that provide structured documentation for your functions and classes.
When working with VS Code or other modern IDEs, these comments will appear as tooltips when you hover over function calls, making it easier for everyone on your team to understand how to use your code.
TypeScript-Specific Comment Directives
TypeScript provides special comment directives that can influence the compiler’s behavior. These are incredibly useful for fine-tuning the type-checking behavior in specific parts of your code.
@ts-ignore Comment in TypeScript
// @ts-ignore
const result = someFunction(); // TypeScript would normally complain about this lineThe @ts-ignore directive tells the TypeScript compiler to ignore any errors on the next line. I use this sparingly, as it can mask real issues, but it’s helpful when dealing with third-party libraries or temporary workarounds.
Check out: TypeScript TypeError: “is not a function”
@ts-expect-error Comment in TypeScript
// @ts-expect-error
const num: number = "not a number"; // We know this will cause an errorThis directive is similar to @ts-ignore, but it expects the next line to have an error. If the line doesn’t produce an error, TypeScript will complain. This is great for ensuring that error cases you’re handling in tests remain errors.
@ts-nocheck Comment in TypeScript
// @ts-nocheck
// None of the TypeScript errors in this file will be reportedWhen placed at the top of a file, this directive disables type checking for the entire file. I primarily use this for JavaScript files that I’m gradually migrating to TypeScript.
Best Practices for TypeScript Comments
After working with TypeScript in large teams, I’ve developed these best practices:
- Be consistent – Choose a commenting style and stick with it throughout your project.
- Comment the “why”, not the “what” – Your code should be self-explanatory about what it does; comments should explain why it does it.
// BAD: Sets user status to active
user.status = 'active';
// GOOD: Status must be updated after verification per legal requirement SEC-2023
user.status = 'active';- Use JSDoc for public APIs – Any function, class, or interface that’s meant to be used by others should have JSDoc comments.
- Keep comments updated – Outdated comments are worse than no comments at all. When you change code, update the comments.
- Avoid comment clutter – Not every line needs a comment. Focus on complex logic, business rules, and non-obvious implementations.
Using Comments for Code Organization
I often use comments to organize sections of code in larger files. This helps with navigation and maintainability.
// ===== User Authentication =====
function login(username: string, password: string): User {
// Authentication logic
}
// ===== Tax Calculations =====
function calculateStateTax(state: USState, income: number): number {
// Tax calculation logic
}This approach is particularly helpful in larger files, making it much easier to locate specific sections of code.
Comment-Driven Development in TypeScript
An approach I’ve found effective in complex TypeScript projects is to write comments first, describing what you’re about to implement. This serves as a kind of pseudo-code, helping to clarify your thinking before writing the actual code.
/**
* Process US tax return
*/
function processTaxReturn(data: TaxReturnData): ProcessedReturn {
// 1. Validate the input data
// 2. Calculate federal tax based on filing status
// 3. Calculate state tax based on residence state
// 4. Apply relevant deductions
// 5. Generate summary and return
}After writing these comment “steps,” I’ll implement each section one by one. This makes complex functions more manageable and helps ensure I don’t miss important steps.
Automatically Generated Comments in TypeScript
Modern TypeScript IDEs, such as VS Code, can automatically generate JSDoc comments for you. Just type /** above a function and press Enter, and it will create a template based on the function’s parameters and return type.
This is a huge time-saver and encourages better documentation practices since it reduces the effort required to write comprehensive comments.
Comments for Future Development in TypeScript
Sometimes I use comments to mark areas that need future attention:
// TODO: Refactor this calculation to support progressive tax brackets
// FIXME: This fails with negative income values
// NOTE: Consider caching these results for performanceMany IDEs will highlight these special comment keywords and even create task lists from them, making it easier to track outstanding work.
Conclusion
I hope you found this article helpful! Well-written comments can transform your TypeScript code from confusing to crystal clear. Remember that comments are not just for others—they’re also for your future self, who will need to understand why you made certain decisions months or years later.
Other TypeScript articles you may also like:
I am Bijay Kumar, a Microsoft MVP in SharePoint. Apart from SharePoint, I started working on Python, Machine learning, and artificial intelligence for the last 5 years. During this time I got expertise in various Python libraries also like Tkinter, Pandas, NumPy, Turtle, Django, Matplotlib, Tensorflow, Scipy, Scikit-Learn, etc… for various clients in the United States, Canada, the United Kingdom, Australia, New Zealand, etc. Check out my profile.
