Skip to content

Commit bc4f537

Browse files
chenwhqldzhwinter
authored andcommitted
Doc: append PADDLE_ENFORCE rules to new_op.md (#12727)
* doc: append PADDLE_ENFORCE rules to new_op_cn.md * doc: polish writing * refactor: polish doc based on advice
1 parent 21ba32b commit bc4f537

File tree

1 file changed

+67
-0
lines changed

1 file changed

+67
-0
lines changed

doc/fluid/dev/new_op_cn.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,3 +334,70 @@ ctest -R test_mul_op
334334
- 注册Op时的类型名,需要和该Op的名字一样。即不允许在`A_op.cc`里面,注册`REGISTER_OPERATOR(B, ...)`等,这将会导致单元测试出错。
335335
- 如果Op没有实现CUDA Kernel,请不要创建空的`*_op.cu`,这将会导致单元测试出错。
336336
- 如果多个Op依赖一些共用的函数,可以创建非`*_op.*`格式的文件来存放,如`gather.h`文件。
337+
338+
### PADDLE_ENFORCE使用注意
339+
340+
实现Op时检查数据的合法性需要使用PADDLE_ENFORCE以及PADDLE_ENFORCE_EQ等宏定义,基本格式如下:
341+
342+
```
343+
PADDLE_ENFORCE(表达式, 错误提示信息)
344+
PADDLE_ENFORCE_EQ(比较对象A, 比较对象B, 错误提示信息)
345+
```
346+
347+
如果表达式为真,或者比较对象A=B,则检查通过,否则会终止程序运行,向用户反馈相应的错误提示信息。
348+
为了确保提示友好易懂,开发者需要注意其使用方法。
349+
350+
#### 总体原则
351+
352+
任何使用了PADDLE_ENFORCE与PADDLE_ENFORCE_**检查的地方,必须有详略得当的备注解释!**错误提示信息**不能为空!
353+
354+
#### 提示信息书写标准
355+
356+
1. [required] 哪里错了?为什么错了?
357+
- 例如:`ValueError: Mismatched label shape`
358+
2. [optional] 期望的输入是什么样的?实际的输入是怎样的?
359+
- 例如:`Expected labels dimension=1. Received 4.`
360+
3. [optional] 能否给出修改意见?
361+
- 例如:`Suggested Fix:If your classifier expects one-hot encoding label,check your n_classes argument to the estimatorand/or the shape of your label.Otherwise, check the shape of your label.`
362+
363+
如果并非必要或者简洁的描述即可表达清楚以上要点,根据情况书写亦可。
364+
365+
##### FAQ 典型问题
366+
367+
1. 无报错信息或报错信息过于简单,不能给用户提供有效的提示!
368+
369+
问题示例1 :未写提示信息
370+
```
371+
PADDLE_ENFORCE(ctx->HasInput("X"), "");
372+
```
373+
问题示例2 :提示信息过于简单
374+
```
375+
PADDLE_ENFORCE(i != nullptr, "I must be set"); // I是什么?
376+
```
377+
378+
2. 在报错信息中使用开发人员定义的变量缩写,不易理解!
379+
380+
问题示例:
381+
```
382+
PADDLE_ENFORCE(forward_pd != nullptr,
383+
"Fail to find eltwise_fwd_pd in device context"); //eltwise_fwd_pd用户可能看不懂
384+
```
385+
386+
#### OP InferShape检查提示信息特别说明
387+
388+
- 检查输入输出变量,请统一遵循以下格式
389+
`Input(变量名) of OP名 operator should not be null.`
390+
391+
正确示例:
392+
```
393+
PADDLE_ENFORCE(ctx->HasInput("Input"),
394+
"Input(Input) of LSTMP operator should not be null.");
395+
```
396+
397+
- 反向Op的输入输出检查,要写明反向Op的名字
398+
399+
正确示例:
400+
```
401+
PADDLE_ENFORCE(ctx->HasInput("X"),
402+
"Input(X) of LoDResetGrad opreator should not be null.");
403+
```

0 commit comments

Comments
 (0)