This file documents the style used in Sourcegraph's code. For non-code text, see the overall content guidelines.
For all things not covered in this document, defer to Go Code Review Comments and Effective Go.
Related pages: Testing Go code | Error handling in Go | Exposing Services
Panics are used for code paths that should never be reached.
In the general case, when a pointer to an "options" struct is an argument
to a function (such as Get(build BuildSpec, opt *BuildGetOptions) (*Build, Response, error)
,
that pointer may be nil
. When the pointer is nil, the function does its default behavior.
If the options struct should not be nil, either make the argument the value instead of a
pointer or document it.
Avoid unnecessary formatting changes that are unrelated to your change. If you find code that isn't formatted correctly, fix the formatting in a separate PR by running the appropriate formatter (e.g. prettier
, gofmt
).
Declare your variables close to where they are actually used.
prefer
a, b := Vector{1, 2, 3}, Vector{4, 5, 6}
a, b := swap(a, b)
c := Vector{7, 8, 9}
total := add([]Vector(a, b, c))...)
over
a, b, c := Vector{1, 2, 3}, Vector{4, 5, 6}, Vector{7, 8, 9}
a, b := swap(a, b)
total := add([]Vector(a, b, c))...)
The c
Vector
isn't used until the add()
function call, so why not declare it immediately beforehand?
By logically grouping components together, you make sure that the context around them isn't lost by the time they come into play. More concretely:
This advice also goes for other types of declarations -- interfaces, structs, etc…
Prefer
var a, b Vector
over
var vectorA, vectorB Vector
Go already encourages short variable names.
In addition, short names:
In the above example, you might think that the names vectorA
and vectorB
are good because you're putting context inside the name itself. That way, there's no confusion / ambiguity when the variables are referred to elsewhere. However, this is redundant / not necessary if you're following the group code blocks logically advice above.
Prefer
var total, scaled Vector
over
var tVec, sVec Vector
Using meaningful names reduces the amount of work that a person has to do to understand what’s going on in your code. More concretely:
Whenever possible, prefer meaningful names over explanatory comments. Comments are an extra thing to navigate around, and they don't actually reduce the amount of jumping around the codebase that you'll need to do when the variables are used later on.
Prefer
var total Vector
func add(...)
over
var tVec Vector
var addAllVecs(...)
Pronounceable names:
Now, something you may have noticed during the demo, is how screen readers handle variable names. It’s rough, right?
@juliaferraioli shared an anecdote about how she spent about 15 minutes scratching her head during a code review the other day, wondering what “gee-thub” was, before she realized that it was reading “GitHub”.
So make sure you use pronounceable names. Don’t make up words. Think of how they would be spoken. Avoid concatenated variable names when possible. Various screen readers won’t necessarily make it clear that the variable name is one word.
a, b := Vector{1, 2, 3}, Vector{4, 5, 6}
a, b := swap(a, b)
c := Vector{7, 8, 9}
total := add([]Vector(a, b, c))...)
If we revisit the recommended organization, we can also see the usage of new lines. Newlines are something we kind of pepper in our code without really thinking about it. However, they can be really powerful signals. I recommend that you treat them like paragraph breaks -- if you don’t use any at all, your reader is lost. If you use them too much, your message is fragmented. They can help guide the user to where the logical components are.
Be intentional with them!
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。