首页 > 其他分享 >Go 100 mistakes - #15: Missing code documentation

Go 100 mistakes - #15: Missing code documentation

时间:2024-02-14 16:35:01浏览次数:39  
标签:comment code 15 Missing package documentation should Go

Documentation is an important aspect of coding. It simplifies how clients can consume an API but can also help in maintaining a project. In Go, we should follow some rules to make our code idiomatic.

First, every exported element must be documented. Whether it is a structure, an interface, a function, or something else, if it’s exported, it must be documented. The convention is to add comments, starting with the name of the exported element. For example,

As a convention, each comment should be a complete sentence that ends with punctuation. Also bear in mind that when we document a function (or a method), we should highlight what the function intends to do, not how it does it; this belongs to the core of a function and comments, not documentation. Furthermore, the documentation should ideally provide enough information that the consumer does not have to look at our code to understand how to use an exported element.

 

When it comes to documenting a variable or a constant, we might be interested in conveying two aspects: its purpose and its content. The former should live as code documentation to be useful for external clients. The latter, though, shouldn’t necessarily be public. For example,

 

To help clients and maintainers understand a package’s scope, we should also document each package. The convention is to start the comment with // Package followed by the package name:

The first line of a package comment should be concise. That’s because it will appear in the package (figure 2.11 provides an example). Then, we can provide all the information we need in the following lines.

Documenting a package can be done in any of the Go files; there is no rule. In general, we should put package documentation in a relevant file with the same name as the package or in a specific file such as doc.go.

One last thing to mention regarding package documentation is that comments not adjacent to the declaration are omitted. For example, the following copyright comment will not be visible in the produced documentation:

 

标签:comment,code,15,Missing,package,documentation,should,Go
From: https://www.cnblogs.com/zhangzhihui/p/18015274

相关文章

  • Debug: tf_distribute_strategy_worker.yaml: Exit Code: 132, and log of pod is emp
    [ERROR:ExitCode:132,andlogofpodisempty.](base)maye@maye-Inspiron-5547:~/github_repository/tensorflow_ecosystem/distribution_strategy$kubectldescribepoddist-strat-example-worker-1-qv8wpName:dist-strat-example-worker-1-qv8wpNa......
  • Codeforces Round 925 (Div. 3)
    CodeforcesRound925(Div.3)A-RecoveringaSmallString解题思路:枚举.代码:#include<bits/stdc++.h>usingnamespacestd;usingll=longlong;usingpii=pair<ll,ll>;#definefifirst#definesesecondusingi128=__int128_t;usingpiii=pa......
  • Debug: tf-distribute-strategy-worker: json.decoder.JSONDecodeError: Expecting pr
    [ERROR:json.decoder.JSONDecodeError:Expectingpropertynameenclosedindoublequotes:line1column182]#infilepipeline.yaml-name:TF_CONFIGvalue:"{\"cluster\":{\"worker\":[\"dist-s......
  • Codeforces 1657E Star MST
    记边权上限为\(W\)。转化一下即为\((1,i)(i\in[2,n])\)的边组成的也是原图的最小生成树。考虑\(\text{Prim}\)的方法求最小生成树。从\(1\)号点开始扩展,每次都会选取距离当前已扩展到的点最近的点\(u\)。为了保证\((1,u)\)的边在最小生成树中,需要满足对于已经扩......
  • CodeForces 1931G One-Dimensional Puzzle
    洛谷传送门CF传送门什么[ABC336G]16Integers究极弱化版。把元素\(1\)看成\(01\),元素\(2\)看成\(10\),元素\(3\)看成\(11\),元素\(4\)看成\(00\)。则转化为统计长度为\(2\)的子串\(xy\)出现次数为\(c_{xy}\)的\(01\)串个数。把子串\(xy\)看成\(x\to......
  • leetcode——数组算法——前缀和构建和应用
    leetcode——数组算法——前缀和构建和应用前缀和技巧适用于快速、频繁地计算一个索引区间内的元素之和303.区域和检索-数组不可变比如leetcode303.区域和(检索-数组不可变)题目介绍:给定一个整数数组nums,处理以下类型的多个查询:计算索引left和right(包含left......
  • Codeforces Round 113 (Div. 2)E. Tetrahedron(dp、递推)
    目录题面链接题意题解代码总结题面链接E.Tetrahedron题意从一个顶点出发走过路径长度为n回到出发点的方案总数题解考虑dp\(f[i][0|1|2|3]\):走了i步,现在在j点的方案总数转移:\(f[i][0]=f[i-1][1]+f[i-1][2]+f[i-1][3]\)\(f[i][1]=f[i-1][0]+f[i-1][2]+f[i-1][3]\)\(f......
  • Codeforces Round 169 (Div. 2)C. Little Girl and Maximum Sum(差分、贪心)
    目录题面链接题意题解代码总结题面链接C.LittleGirlandMaximumSum题意给q个[l,r]将所有这些区间里面的数相加和最大。可以进行的操作是任意排列数组题解对出现的每个区间内的位置加上1,代表权值操作完之后求一遍前缀和,得到每个位置的权值然后贪心的考虑,权值越大,应......
  • CodeForces 1928F Digital Patterns
    洛谷传送门CF传送门为什么我场上被卡常了。转化题意,将\(a,b\)差分,答案为在\(a,b\)选出相同长度的不含\(0\)的子段方案数。设\(a\)选出长度为\(i\)的不含\(0\)的子段方案数为\(x_i\),\(b\)选出长度为\(i\)的不含\(0\)的子段方案数为\(y_i\)。答案为\(\su......
  • day15_scp与ntp服务
    今日笔记,服务管理回顾systemctl你的机器,会有默认的软件(服务),network管理网络的软件,sshd提供远程连接的软件对这些服务,进行管理启动停止重启重新加载开机自启(持久化)禁止开机自启查询是否持久化(是否开机自启)centos7,用这个命令,同时对服务进行启停管理,以及开机自启......