Code Smell 278 - DirName and File

Avoid Ambiguous Naming for Path Variables

Maximiliano Contieri

Nov 10, 2024

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

Honor the Bijection
Use precise names
Avoid ambiguity
Keep context clear
Extract reusable code
Follow naming conventions
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.

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

Without Proper Instructions

With Specific Instructions

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

Code Smell 33 - Abbreviations

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

Software Engineering Great Quotes

This article is part of the CodeSmell Series.

How to Find the Stinky Parts of your Code

Clean Code Cookbook

Discussion about this post