atppp's Blog

微软的文档……

同样是字符串里找子串的函数，微软 VB 的文档：

Returns an integer specifying the start position of the first occurrence of one string within another.

Public Shared Function InStr(_
    ByVal String1 As String, _
    ByVal String2 As String, _
    Optional ByVal Compare As CompareMethod _
) As Integer

Parameters

String1
Required. String expression being searched.

String2
Required. String expression sought.

读完了一头雾水，TMD 到底哪个参数是要找的子串？？being searched？sought？？我英语不好也不要这么欺负我啊。再看微软 VC++ 类似函数的文档：

Return a pointer to the first occurrence of a search string in a string.

char *strstr(
   const char *str,
   const char *strSearch
); // C only

Parameters

str
Null-terminated string to search.

strSearch
Null-terminated string to search for.

Return Value
Returns a pointer to the first occurrence of strSearch in str …

VC++ 里解释比 VB 的稍好一些，但是还是不清不楚的，功能说明为啥不写清楚哪个 string 是哪个呢？变量名为什么要写得这么诡异呢？参数说明里一个是 search，一个是 search for，TMD 又欺负我英语差！像这种常用函数，一般人都知道大概怎么用，只是偶尔不确定看一下参数顺序，你这么个文档还得让人费脑细胞琢磨，要你何用！再看 PHP 里类似的函数：

int strpos ( string $haystack, mixed $needle [, int $offset ] )

Returns the numeric position of the first occurrence of needle in the haystack string.

PHP 这个文档光看参数名就足以明白参数顺序了，看了功能解释就更清楚了。MacOS 的 man page：

char *strstr(const char *big, const char *little);

The strstr() function locates the first occurrence of the null-terminated string little in the null-terminated string big.

有一百种方法可以把这个函数的参数顺序写的很明确，但是微软偏偏选择了不明朗的写法。想起一般微软的程序很少有人去看 HELP 解决问题，而 MacOS 和 *nix 下面看文档则是家常便饭，看来微软文档无用论还是很有道理的……

Tags: documentation, microsoft, usability