Я хочу использовать правильный термин для создания моего API максимально интуитивным, поэтому когда параметр, как ожидают, будет полным путем и именем файла (исключая "C:\Users\Max\Documents\MyDocument.txt"), каков правильный термин?
Что я должен использовать для названия параметра? "Файл" был бы соответствующим именем?
Я чувствую вид немого выяснения у этого, но я хочу удостовериться, что это правильно.
Правильным термином является "Полностью квалифицированное имя" (иногда "FQN").
Термин, который вы должны использовать в вашем API - "QualifiedName" или "QualifiedFilename"
Википедия имеет запись для "Fully qualified file name" и определяет его как "файл на компьютере, точное имя которого полностью указано так, что оно является однозначным и не может быть ошибочно принято за любой другой файл в этой системе"
.Для этого термина часто слишком часто используется URI, хотя Ваш пример на самом деле не один из них. Я думаю, что Вам будет совершенно ясно, если Вы просто используете "filepath" или "pathname".
Например, в качестве имени параметра для конструктора в своем File объекте Java's file object использует "pathname".
Я бы пошел с fullPath, как вы сказали, путь будет C: \ Users \ Max \ Documents, но чтение fullPath предложит путь + имя файла.
Я не думаю, что есть "Один истинный ответ", может быть, какой-то консенсус, но это все, на что мы можем надеяться. Обычно я стараюсь следовать конвенциям библиотеки, которую использую (например, Cocoa, Java или PHP). Если бы мне нечего было сказать, я бы сказал:
/Users/Max/Documents/FooBar
, .../Sibling/Zardoz
FooBar
, Zardoz
, Documents
Обычно путь - это полный C:\Users\Max\Documents\MyDocument.txt
, в то время как C:\Users\Max\Documents\
часть обычно называется базовым каталогом или просто каталогом.
Вы увидите во многих примерах кода, который пишут люди: C:\path\to\the\document.txt
Мое предложение было бы «Абсолютный путь к файлу» для некоторого пути, указывающего на файл, тогда как я бы использовал «Абсолютный путь к каталогу» для пути, указывающего на каталог
В случае относительных путей изменение должно быть очевидным.
По крайней мере, вы всегда можете сделать раздел в своей документации, где вы опишете значение определенных терминов, которые вы используете.
Одно более простое решение, которое вы, возможно, уже рассматривали, - это сообщить потребителю API, что ожидается в документации XML, которая также появится в Visual Studio intellisense, если вы скомпилируете сборку с документацией и распространите файл .xml.
/// <summary>
/// Saves the provided file to disk.
/// </summary>
/// <param name="filePath">The full path, including the filename of the file.</param>
public void SaveFile(string filePath)
{
}