ZAČÁTKYNÁVODYOOPDOKUMENTACE
教程/
文体和惯例

纪录片评论,捷克语还是英语?

22. 08. 2019

Obsah článku

编写文档需要时间,而且往往没有人在你之后读它,所以直接在源代码中写注释是一个好的做法。然而,大量的文字不必要地使代码变得杂乱无章,然后可能无法同时在显示器上显示,再次降低其可读性。

因此,任何代码都应该是**不言而喻的,也就是说,当阅读它时,应该立即清楚它的作用,而且它应该只做一件事。

例如,如果一个函数被命名为 "getUserProfileById($id)",那么这样的函数是做什么的,以及我们可以期待什么样的返回值,就非常清楚了。这就是为什么注释经常被用来只描述输入和输出参数+对原理的简短文字解释(如果有更复杂的事情发生)。当代码是为多人准备的,礼貌的做法是包括作者和创建日期。

/**
* 如果传递的值是一个有效的IPv6地址,则返回TRUE。
* 替代正则表达式。
* /^(((?=(?>.*?(::))(?!.+\3)))\3?|([\dA-F]{1,4}(\3|:(?!$)|$)|\2))
(?4){5}((?4){2}|((2[0-4]|1\d|[1-9])?\d|25[0-5])(\.(?7)){3})\z/i
* @作者Jan Barasek
*/
function isIpV6(string $value): bool
{
if (str_contains($value, ':')) {
return (bool) filter_var($value, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6);
}
return false;
}

从注释中可以看出,该函数希望输入一个IPv6地址,并根据验证的情况返回一个布尔值TRUEFALSE

bootstrap注解用于使用标准化的键来表示数值,许多编辑器可以进一步处理,例如,在调用函数时提示参数,或者自动传递依赖关系。

直接在代码内的注释只在特殊情况下使用。如果代码需要一个内部注释,这通常表明它应该被分解成多个较小的部分,这些部分将解决自己的那部分程序。

语言

习惯上总是用英文来命名类、方法、函数和变量(以使大量的程序员能够阅读代码),键是相对标准化的,有统一的语法,所以语言在这里也不重要,而对于帮助文本,则取决于项目的用法。如果是一个稳定的团队的小项目,英语不一定是个问题,相反,至少每个人都能完全理解描述的内容。

使用注释的动机

特殊字符(呼号)可以被编辑器以外的其他工具注意到,所以很有用,例如,把它的测试(在什么输入我期待什么输出)直接放在函数定义的上方,这样就不会忘记写测试的地方,同时每个程序员都能立即知道这个函数是干什么的。

这里有一个测试定义的小例子(它只是一个符号的概念,并不是一个具体的测试工具)。

Dosadí hodnoty a vynutí jejich dump do prohlížeče / konzole:
@test Název I---> $limit => {1-{5-8}}, $city => {Praha|Kladno|Brno|Plzeň} O---> [DUMP]
Vygeneruje náhodný hash o délce 6 znaků a ověří, zda je hlavička odpovědi jakákoli, kromě 201:
@test Název I---> $hash => {a-z0-9|len:6} O---> [HEADER:***|!HEADER:201]
Vygeneruje dvojici čísel a na výstupu ověří jejich součet:
@test Sčítání čísel I---> $a => {1-5}, $b => {7-12} O---> ($return == $a+$b)
Načte náhodný článek s ID mezi 1 až 30, ověří jeho délku nebo neprázdnost:
@test Získání textu článku I---> $id => {1-30} O---> (strlen($return) > 64 || $return != NULL)
Vygeneruje náhodnou IP adresu a ověří, zda je z České republiky:
@test Geolokace I---> $ip => {1-255}.{1-255}.{1-255}.{1-255} O---> ($return['国家'] == 'EN')
Pokusí se načíst článek s vysokým ID a při testování mrkne na modifikátory (filtry):
@test Neexistující článek I---> $id => {1000000+} O---> [HEADER:4**:3**|NOCONTENT]
Vrátí počet rohů jednorožce:
@test Jednorožec I---> $maRohy => TRUE O---> 1
Kolik prstů ukazuji?
@test Prsty I---> $ukazuji => {0-10|NAME:prsty} O---> ($return == {*|NAME:prsty})

其中一般会写,比如说,根据规则。

@test <název_testu> I---> $<proměnná> => <hodnota> O---> [<modifikátor>:<hodnota>] (<výraz_platnosti>)

在测试里面,我使用了一个使用正则表达式的随机值生成器。 这里有一些例子。

{<hodnota><směr_nerovnosti>} {500+} {250-} {-200-(-50)}
{<začátek>-<konec>} {0-5} {a-z} {a-f0-9}
{<Hodnota1>|<Hodnota2>|<Hodnota3>} {Praha|Kladno|Brno}
{<výraz>|<modifikátor>:<hodnota>} {a-z0-9|len:6} {*|len:6}
{*|<modifikátor>:<hodnota>} {*|randomWord:5}

Jan Barášek   Více o autorovi

Autor článku pracuje jako seniorní vývojář a software architekt v Praze. Navrhuje a spravuje velké webové aplikace, které znáte a používáte. Od roku 2009 nabral bohaté zkušenosti, které tímto webem předává dál.

Rád vám pomůžu:

Související články

1.
4.