TL;DR: Use clear names for better code understanding.

Problems

• Unclear variable purpose
• Bijection Fault
• Misleading context
• Repetitive code
• Harder maintenance
• Reduced readability
• Abbreviations
• Increased cognitive load

Solutions

1. Honor the Bijection
2. Use precise names
3. Avoid ambiguity
4. Keep context clear
5. Extract reusable code
6. Follow naming conventions
7. Reify names with their rules

Context

When handling a single fileName or directoryPath, vague names like file or dirName create confusion.

• A file should represent a File
• A fileName should represent the name of a file
• fileContents should represent the content of a file
• A fileHandler should represent a pointer to an external resource
• dirName should be directoryPath

Clear names like fileName for names and directoryPath for directories communicate each variable’s role.

When you name a variable file, it can confuse others about its purpose. Does it store a file object or just the filename?

When you name a variable dirName instead of directoryName it leads to ambiguity.

Clear and descriptive variable names improve code readability and maintainability, especially in collaborative environments.

Sample Code

Wrong

function importBoardGameScores(file) {
  if (file) {
    const data = fs.readFileSync(file, 'utf-8');
    // Process board game scores...
  }
}

function importDirectoryScores(dirName) {
  // 'dir' is an abbreviation
  const files = fs.readdirSync(dirName);
  files.forEach(file => {
    const data = fs.readFileSync(`${dirName}/${file}`, 'utf-8');
    // Process each file's board game scores...
  });
  }
}

Right

function importBoardGameScores(fileName) {
  if (fileName) {
    const data = fs.readFileSync(fileName, 'utf-8');
    // Process board game scores...
  }
}

function importDirectoryBoardGamesScores(directoryPath) {
    const fileNames = fs.readdirSync(directoryPath);
    // Note the variable holding filenames 
    // and not files

   fileNames.forEach(filename => {
        const fullPath = path.join(directoryPath, filename);
        const scores = importBoardGameScores(fullPath);
        allScores.push(scores);
   });

   return allScores.flat();


// You can also reify the concept of a filename
// And avoid repeating the rules everywhere

class Filename {
    value;

    constructor(value) {
        this.validateFilename(value);
        this.value = value;
    }

    validateFilename(value) {      
        const invalidCharacters = /[<>:"/\\|?*\x00-\x1F]/g;
        if (invalidCharacters.test(value)) {
            throw new Error
              ('Filename contains invalid characters');
        }

        if (/^[. ]+$/.test(value)) {
            throw new Error
              ('Filename cannot consist only of dots or spaces');
        }

        if (value.length > 255) {
            throw new Error
              ('Filename is too long');
        }
    }

    toString() {
        return this.value;
    }

    get value() {
        return this.value;
    }
}

Detection

[X] Semi-Automatic

Look for generic names in code handling files or directory paths like file or dirName.

Tags

• Naming

Level

[x] Beginner

AI Generation

AI models may default to ambiguous names like file or dirName without specific instructions.

Adding descriptive naming and code extraction guidelines can improve the AI's output.

AI Detection

AI tools can fix this smell by using clear naming conventions and suggesting code extraction if prompted to avoid redundant code.

Try Them!

Remember: AI Assistants make lots of mistakes

Conclusion

By using precise names like fileName and directoryPath and extracting reusable methods, you improve code clarity and maintainability.

These simple practices help reduce redundancy and keep your code understandable.

Relations

Disclaimer

Code Smells are my opinion.

Credits

Photo by Gabriel Heinzer on Unsplash

---

Code should be written to be read by humans first, and machines second.

Don Laabs

---

This article is part of the CodeSmell Series.