Maison > Article > développement back-end > Quelle est la spécification de codage des commentaires du langage Go ?
Spécifications de codage des annotations : 1. Tous les objets exportés doivent être annotés pour expliquer leur objectif ; les objets non exportés doivent être annotés en fonction de la situation. 2. Si l'objet est dénombrable et que la quantité n'est pas clairement spécifiée, utilisez toujours la forme singulière et le temps continu sinon, utilisez la forme plurielle ; 3. Les commentaires sur les packages, les fonctions, les méthodes et les types sont tous des phrases complètes. 4. Les premières lettres des commentaires de type phrase doivent être en majuscules ; les premières lettres des commentaires de type phrase doivent être en minuscules. 5. La longueur d'une seule ligne de commentaires ne peut pas dépasser 80 caractères.
L'environnement d'exploitation de ce tutoriel : système Windows 7, GO version 1.18, ordinateur Dell G3.
Les commentaires peuvent nous aider à bien terminer le travail documentaire, et des commentaires bien rédigés peuvent faciliter notre maintenance future. Le commentaire de bloc de
/**/
et le commentaire sur une seule ligne de //
sont deux styles de commentaire afin d'unifier le style, tous sur une seule ligne. les commentaires de ligne sont utilisés dans notre projet. La qualité des annotations détermine la qualité des documents générés. /**/
的块注释和 //
的单行注释两种注释风格, 在我们的项目中为了风格的统一,全部使用单行注释,注释的质量决定了生成的文档的质量。
所有导出对象都需要注释说明其用途;非导出对象根据情况进行注释。
如果对象可数且无明确指定数量的情况下,一律使用单数形式和一般进行时描述;否则使用复数形式。
包、函数、方法和类型的注释说明都是一个完整的句子。
句子类型的注释首字母均需大写;短语类型的注释首字母需小写。
注释的单行长度不能超过80个字符。
1、包级别
包级别的注释就是对包的介绍,只需在同个包的任一源文件中说明即可有效。【相关推荐:Go视频教程、编程教学】
每个包都应该有一个包注释,一个位于 package 子句之前行注释
包注释应该包含下面基本信息
// @Title 请填写文件名称(需要改) // @Description 请填写文件描述(需要改) // @Author 请填写自己的真是姓名(需要改) ${DATE} ${TIME} // @Update 请填写自己的真是姓名(需要改) ${DATE} ${TIME} package ${GO_PACKAGE_NAME}
2、结构(接口)注释
每个自定义的结构体或者接口都应该有注释说明,该注释对结构进行简要介绍,放在结构体定义的前一行,格式为: 结构体名, 结构体说明。同时结构体内的每个成员变量都要有说明,该说明放在成员变量的后面(注意对齐),实例如下:
// User 用户对象,定义了用户的基础信息 type User struct{ Username string // 用户名 Email string // 邮箱 }
3、函数(方法)注释
每个函数,或者方法(结构体或者接口下的函数称为方法)都应该有注释说明
函数的注释应该包括三个方面
// @title 函数名称 // @description 函数的详细描述 // @auth 作者 时间(2019/6/18 10:57 ) // @param 输入参数名 参数类型 "解释" // @return 返回参数名 参数类型 "解释"
4、代码逻辑注释
每个代码块都要添加单行注释
注视使用 TODO 开始 详细如下
// TODO 代码块的执行解释 if userAge < 18 { }
其它说明
当某个部分等待完成时,可用 TODO:
开头的注释来提醒维护人员。
当某个部分存在已知问题进行需要修复或改进时,可用 FIXME:
开头的注释来提醒维护人员。
当需要特别说明某个问题时,可用 NOTE:
// NOTE: os.Chmod and os.Chtimes don't recognize symbolic link, // which will lead "no such file or directory" error. return os.Symlink(target, dest)🎜🎜2.Annotation de la structure (interface)🎜🎜🎜Chaque structure ou interface personnalisée doit avoir une annotation. L'annotation présente brièvement la structure et est placée dans la définition de la structure. le format est : nom de la structure, description de la structure. En même temps, chaque variable membre de la structure doit avoir une description, qui est placée après la variable membre (faites attention à l'alignement). Les exemples sont les suivants : 🎜rrreee🎜🎜3 Commentaires sur la fonction (méthode) 🎜🎜🎜🎜. 🎜Chaque fonction ou méthode (les fonctions sous les structures ou les interfaces sont appelées méthodes) doit avoir des commentaires 🎜🎜🎜🎜 Les commentaires sur les fonctions doivent inclure trois aspects 🎜🎜🎜rrreee🎜🎜4 Commentaires sur la logique du code 🎜🎜🎜🎜🎜Chaque bloc de code Vous. doit ajouter un commentaire d'une seule ligne🎜🎜🎜🎜 Regardez l'utilisation de TODO Les détails sont les suivants🎜🎜🎜rrreee🎜🎜Autres instructions🎜🎜🎜🎜🎜Lorsqu'une certaine partie est en attente d'être complétée, vous pouvez utiliser des commentaires commençant par
À FAIRE :
Alerter le personnel de maintenance. 🎜🎜🎜🎜Lorsqu'une certaine pièce présente un problème connu qui doit être corrigé ou amélioré, vous pouvez utiliser un commentaire commençant par FIXME :
pour alerter le responsable. 🎜🎜🎜🎜Lorsque vous avez besoin d'expliquer spécifiquement un problème, vous pouvez utiliser un commentaire commençant par REMARQUE :
: 🎜🎜🎜rrreee🎜Pour plus de connaissances liées à la programmation, veuillez visiter : 🎜Introduction à la programmation🎜 ! ! 🎜Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!