New Story

Code Smell 278 - DirName and File

by Maximiliano ContieriNovember 11th, 2024

Too Long; Didn't Read

This guide emphasizes the importance of using clear and descriptive variable names like fileName and directoryPath in coding to avoid confusion and improve readability. It highlights the benefits of precise naming conventions, including better maintainability and easier collaboration. Additionally, it offers sample code demonstrating the difference between ambiguous and clear variable names.

featured image - Code Smell 278 - DirName and File

Avoid Ambiguous Naming for Path Variables

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;
    }
}