I’m seeking vital naming of string filename
parameter in parameter list used in various methods where filename with full path is expected. In many cases also UNC path can be actually supplied as full path because many libraries handle it natively.
I usually call the parameter just filename
, but it can be misleading in two ways:
- Beginners tend to think it is only name of file – without path.
- If there is a need of splitting the value into path and filename, term filename sticks better with filename part without path which appeared after split. Anyway, it is not easy to give that second part better name than
filename
. Alternative of splittingfilename
topath
andfilenameOnly
looks weird to me.
I think it might be better to use clearly distinguishable term for filename with path than borrowing filename which already has stronger meaning for something else.
I was thinking about term absoluteFilePath
or fullyQualifiedFilename
to stand as argument names. Maybe they are good and I need only some encouragement to start using them, but I would like to understand your best practices.
EDIT: I would still like to stick with official VB.NET naming and capitalization conventions, so the only thing I need help sharpening is clear self-documenting wording of the term. (Not whether I should use Hungarian notation or not – I cannot.)
6
It sounds like you’d be safer defining a code contract.
You can say a precondition of this method is that the path supplied is an absolute path.
You can make this clearer by naming the input parameter String absolutePathToFile
.
And finally, you can make your method fail early if the preconditions aren’t met. Do this by checking if the absolutePathToFile
is indeed an absolute path. If not, throw an argument exception.
So, instead of simply picking a parameter name and hoping the next developers a) pay attention to it, and b) understand it the same way you do (both of which are unlikely), you do the following:
- Code Contract: Explicitly declare your method preconditions. You can put this in your documentation, or as inline method documentation (if your language/ide supports it)
- Self Documenting Code: Choose a parameter name that describes what you want as clearly as possible (not always easy)
- Defensive Programming: Check your method parameters to see if they’re valid. If not, fail hard and fail early.
5