4

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 splitting filename to path and filenameOnly 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.)

closed as primarily opinion-based by gnat, World Engineer Apr 20 '14 at 19:28

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • fullPath sounds good to me. – Brandon Apr 20 '14 at 13:34
  • @Brandon - if someone instantly reads list of parameters, seeing fullPath won't necessarily tell him 'file goes here'. Following your idea, fullFilePath or fullPathToFile might be better – miroxlav Apr 20 '14 at 14:28
  • Though, in my experience, then technical terms you're looking for here are relative and absolute paths. – MetaFight Apr 20 '14 at 14:49
  • @MetaFight - basically I agree, my comment was addressing another aspect of name creation in hope it could help someone – miroxlav Apr 20 '14 at 14:56
  • to downvoters: besides downvoting, please leave comment (this is recommended SE practice) how the question can be improved or if you think it is off-topic, please state why. For me and some other users discussing this was useful. – miroxlav Apr 20 '14 at 16:04
4

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:

  1. 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)
  2. Self Documenting Code: Choose a parameter name that describes what you want as clearly as possible (not always easy)
  3. Defensive Programming: Check your method parameters to see if they're valid. If not, fail hard and fail early.
  • In rare cases, filename without path can be supplied, too. Underlying libraries can handle it and I do not want to artifically prevent this. If filename without path is supplied then path of currently launched executable is assumed. At the moment I cannot afford testing wave triggered by suggested modification – because of large size of the application. (I only joined the work on existing project.) But generally your idea of code contracts is good, I appreciate it. String absolutePathToFile is also a good idea. – miroxlav Apr 20 '14 at 14:18
  • 1
    I'd advise against building your system to implicitly support rare cases. If these cases are known, then detect them and normalize the data so that it becomes the general case. In your example, maybe you should check the nature of the path before calling your function. If it's just a filename, then convert it to an absolute path of that filename in the launched executable's folder. This way your method's concern is still just absolute paths, and your known rare case is addressed as well. – MetaFight Apr 20 '14 at 14:46
  • "In rare cases, filename without path can be supplied, too." - honestly, the way you describe this in your comment, it sounds like you just want to use the standard convention of standard file ops: when no full path is supplied, the partial path is not absolute, but relative to the current directory of the current process or thread. If that's true, a name like absolutePathToFile would be pretty misleading. – Doc Brown Apr 20 '14 at 16:32
  • @MetaFight – I will go with your recommendations, implementing them in long-term change cycle. Thank you again. – miroxlav Apr 22 '14 at 19:26
  • @DocBrown – My conclusion after some time has passed: I have considered DocBrown's comment, too – it has a good point. Where the parameter is subject of processing only by generic file functions which do not necessarily require absolute path (and where I won't implement the enforcement of absolute path), I will name it pathToFile (including derived forms like pathToSettingsFile or pathToFileFromWebservice etc.). I will use absolutePathToFile (absolutePathToSettingsFile, absolutePathToFileFromWebservice, ...) only where absolute path is a strict requirement. – miroxlav May 4 '14 at 11:09

Not the answer you're looking for? Browse other questions tagged or ask your own question.