This content originally appeared on DEV Community and was authored by Maxi Contieri

Clean up your code by removing unnecessary 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

Related Code Smells

Code Smell 151 – Commented Code

Maxi Contieri ・ Jul 22 ’22

#javascript #webdev #beginners #programming

Code Smell 183 – Obsolete Comments

Maxi Contieri ・ Dec 2 ’22

#database #performance #pgaichallenge #postgres

Code Smell 152 – Logical Comment

Maxi Contieri ・ Jul 24 ’22

#javascript #webdev #beginners #programming

Code Smell 146 – Getter Comments

Maxi Contieri ・ Jul 2 ’22

#javascript #webdev #beginners #programming

Code Smell 05 – Comment Abusers

Maxi Contieri ・ Oct 24 ’20

#codenewbie #tutorial #beginners

Code Smell 168 – Undocumented Decisions

Maxi Contieri ・ Oct 11 ’22

#webdev #beginners #programming #tutorial

Code Smell 148 – ToDos

Maxi Contieri ・ Jul 13 ’22

#javascript #webdev #beginners #programming

Steps

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.

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.

Tags

• Comments

Level

[X] Intermediate

Related Refactorings

Refactoring 005 – Replace Comment with Function Name

Maxi Contieri ・ Jun 7 ’22

#javascript #beginners #refactorit #programming

Refactoring 011 – Replace Comments with Tests

Maxi Contieri ・ Apr 23 ’23

#webdev #beginners #programming #tutorial

Credits

Image by congerdesign on Pixabay

This article is part of the Refactoring Series.

How to Improve your Code With easy Refactorings

Maxi Contieri ・ Oct 24 ’22

#webdev #beginners #programming #tutorial

This content originally appeared on DEV Community and was authored by Maxi Contieri