TL;DR: Make your code simpler and more maintainable by removing redundant or unused annotations.

Problems Addressed 😔

Obsolete comments
Cluttered code
Lower readability
Maintenance overhead
Unnecessary metadata
Overengineered solutions
Metaprogramming
Hidden design decisions
To-dos

https://maximilianocontieri.com/code-smell-151-commented-code

https://maximilianocontieri.com/code-smell-183-obsolete-comments

https://maximilianocontieri.com/code-smell-152-logical-comment

https://maximilianocontieri.com/code-smell-146-getter-comments

https://maximilianocontieri.com/code-smell-05-comment-abusers

https://maximilianocontieri.com/code-smell-168-undocumented-decisions

https://maximilianocontieri.com/code-smell-148-todos

Steps 👣

Identify annotations bloating your code.
Evaluate their purpose and necessity.
Remove annotations with no clear value.
Replace critical annotations with explicit code.

Sample Code 💻

Before 🚨

<?php
// @author John Wick
// @version 3.14
// @description Service for user operations
class UserService {
    /**
     * @deprecated
     * @param int $id
     * @return string
     */
    public function userName($id) {
        // @todo Sanitize input
        return $this->database->query(
            "SELECT name FROM users WHERE id = $id");
    }
}

After 👉

<?php
class UserService {
    // Step 1: Identified annotations 
    //   (@author, @version, @description, 
    // Step 2: Evaluated their purpose 
    //   (metadata, deprecated, todo notes)
    // Step 3: Removed unnecessary annotations (no value added)
    // Step 4: Replaced critical annotations 
    //   with explicit code (none needed)

    // Type hintings are explicit
    public function userName(int $id): string {        
        $statement = $this->database->prepare(
          "SELECT name FROM users WHERE id = ?");
        // No tech debt 
        $statement->execute([$id]);
        return $statement->fetchColumn();
        // You can add a test to ensure there are 
        // no new calls to this deprecated method
    }
}

Type 📝

[X] Semi-Automatic

You can rewrite them with expressions or with an AI assistant.

Safety 🛡️

You can safely remove annotations if they’re purely metadata or documentation, but ensure any functional annotations (like @Deprecated) are replaced with explicit code or logic to maintain behavior.

Why is the Code Better? ✨

You get cleaner, easier-to-read, and less cluttered code.

Removing unnecessary annotations reduces maintenance overhead and focuses on the core logic.

Explicit code over annotations improves clarity and reduces reliance on metadata that may become outdated.

How Does it Improve the Bijection? 🗺️

You simplify the mapping between the real-world problem and the code by removing annotations that don’t model the domain.

This creates a clearer, one-to-one correspondence with the problem space, reducing noise and improving maintainability.

Limitations ⚠️

Some annotations (e.g., @Override, @Transactional) are critical for functionality in certain frameworks.

You must carefully evaluate each annotation’s role before removal to avoid breaking behavior.

Refactor with AI 🤖

You can use AI tools like ChatGPT or GitHub Copilot to analyze your codebase. Ask the AI to identify annotations, explain their purpose, and suggest replacements with explicit code. Then, manually review and test the changes to ensure correctness.

Suggested Prompt: 1. Identify annotations bloating your code.2. Evaluate their purpose and necessity. 3. Remove annotations with no clear value. 4. Replace critical annotations with explicit code.

Without Proper Instructions	With Specific Instructions
ChatGPT	ChatGPT
Claude	Claude
Perplexity	Perplexity
Copilot	Copilot
You	You
Gemini	Gemini
DeepSeek	DeepSeek
Meta AI	Meta AI
Grok	Grok
Qwen	Qwen

Tags 🏷️

Comments

Level 🔋

[X] Intermediate

https://maximilianocontieri.com/refactoring-005-replace-comment-with-function-name

https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests

Credits 🙏

Image by congerdesign on Pixabay

This article is part of the Refactoring Series.

https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings

Refactoring 033 - Strip Annotations

Comments

Refactorings

Refactoring 032 - Apply Consistent Style Rules

More from this blog

AI Coding Tip 029 - Stop Using One Model for Everything

AI Coding Tip 028 - Build a Company Brain

AI Coding Tip 027 - Force Code Standards

AI Coding Tip 026 - Assign a Persona to Every Skill Definition

The Dirty Secret Behind Loop Engineering

Problems Addressed 😔

Steps 👣

Sample Code 💻

Before 🚨

After 👉

Type 📝

Safety 🛡️

Why is the Code Better? ✨

How Does it Improve the Bijection? 🗺️

Limitations ⚠️

Refactor with AI 🤖

Tags 🏷️

Level 🔋

Credits 🙏

Command Palette

Comments

Refactorings

Refactoring 032 - Apply Consistent Style Rules

More from this blog

Problems Addressed 😔

Related Code Smells 💨

Steps 👣

Sample Code 💻

Before 🚨

After 👉

Type 📝

Safety 🛡️

Why is the Code Better? ✨

How Does it Improve the Bijection? 🗺️

Limitations ⚠️

Refactor with AI 🤖

Tags 🏷️

Level 🔋

Related Refactorings 🔄

Credits 🙏