This content originally appeared on Level Up Coding - Medium and was authored by Maximiliano Contieri
Code Smell 278 — DirName and File
Avoid Ambiguous Naming for Path Variables
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.
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
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
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
Code Smell 278 — DirName and File was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Maximiliano Contieri
Maximiliano Contieri | Sciencx (2024-11-11T02:49:52+00:00) Code Smell 278 — DirName and File. Retrieved from https://www.scien.cx/2024/11/11/code-smell-278-dirname-and-file-2/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.