Clean up your code by removing unnecessary annotations Clean up your code by removing unnecessary annotations TL;DR: Make your code simpler and more maintainable by removing redundant or unused annotations. 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 Obsolete comments Obsolete comments Cluttered code Lower readability Maintenance overhead overhead Unnecessary metadata Overengineered solutions Metaprogramming Metaprogramming Hidden design decisions design decisions To-dos To-dos Related Code Smells 💨 https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxvii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxvii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx Steps 👣 Identify annotations bloating your code.
Evaluate their purpose and necessity.
Remove annotations with no clear value.
Replace critical annotations with explicit code. 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");
    }
} <?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
    }
} <?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 📝 Semi-Automatic 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. real-world This creates a clearer, one-to-one correspondence with the problem space, reducing noise and improving maintainability. one-to-one Limitations ⚠️ Some annotations (e.g., @Override, @Transactional) are critical for functionality in certain frameworks. (e.g., @Override, @Transactional) 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. 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 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 Without Proper Instructions

With Specific Instructions Without Proper Instructions Without Proper Instructions With Specific Instructions With Specific Instructions ChatGPT

ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT Claude

Claude Claude Claude Claude Claude Claude Claude Perplexity

Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Copilot

Copilot Copilot Copilot Copilot Copilot Copilot Copilot You

You You You You You You You Gemini

Gemini Gemini Gemini Gemini Gemini Gemini Gemini DeepSeek

DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek Meta AI

Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Grok

Grok Grok Grok Grok Grok Grok Grok Qwen

Qwen Qwen Qwen Qwen Qwen Qwen Qwen Tags 🏷️ Comments Comments Level 🔋 [x]Intermediate [x]Intermediate [x] Related Refactorings 🔄 https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests?embedable=true https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests?embedable=true Credits 🙏 Image by congerdesign on Pixabay congerdesign Pixabay This article is part of the Refactoring Series. https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true

Code Smell 04 - Stop Abusing Strings—Use Real Objects Instead

Buy My Book

Refactoring 033 - Removing Redundant or Unused Annotations

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

10 Predictions About the Future of Finance

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

4 Simple Habits For Engineering Teams To Beat Technical Debt

10 Predictions About the Future of Finance

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

4 Simple Habits For Engineering Teams To Beat Technical Debt

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps