diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 89 |
1 files changed, 44 insertions, 45 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4382ec..afb7d4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,3 @@ -<!-- use this template to generate the contributor docs with the following command: `$ lingo run docs --template CONTRIBUTING_TEMPLATE.md --output CONTRIBUTING.md` --> # Contributing to excelize Want to hack on excelize? Awesome! This page contains information about reporting issues as well as some tips and @@ -376,89 +375,89 @@ reading through [Effective Go](https://golang.org/doc/effective_go.html). The kool-aid is a lot easier than going thirsty. ## Code Review Comments and Effective Go Guidelines -[CodeLingo](https://codelingo.io) automatically checks every pull request against the following guidelines from [Effective Go](https://golang.org/doc/effective_go.html) and [Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments). +[CodeLingo](https://codelingo.io) automatically checks every pull request against the following guidelines from [Effective Go](https://golang.org/doc/effective_go.html) and [Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments). ### Package Comment -Every package should have a package comment, a block comment preceding the package clause. -For multi-file packages, the package comment only needs to be present in one file, and any one will do. -The package comment should introduce the package and provide information relevant to the package as a -whole. It will appear first on the godoc page and should set up the detailed documentation that follows. +Every package should have a package comment, a block comment preceding the package clause. +For multi-file packages, the package comment only needs to be present in one file, and any one will do. +The package comment should introduce the package and provide information relevant to the package as a +whole. It will appear first on the godoc page and should set up the detailed documentation that follows. ### Single Method Interface Name -By convention, one-method interfaces are named by the method name plus an -er suffix + +By convention, one-method interfaces are named by the method name plus an -er suffix or similar modification to construct an agent noun: Reader, Writer, Formatter, CloseNotifier etc. -There are a number of such names and it's productive to honor them and the function names they capture. -Read, Write, Close, Flush, String and so on have canonical signatures and meanings. To avoid confusion, -don't give your method one of those names unless it has the same signature and meaning. Conversely, -if your type implements a method with the same meaning as a method on a well-known type, give it the +There are a number of such names and it's productive to honor them and the function names they capture. +Read, Write, Close, Flush, String and so on have canonical signatures and meanings. To avoid confusion, +don't give your method one of those names unless it has the same signature and meaning. Conversely, +if your type implements a method with the same meaning as a method on a well-known type, give it the same name and signature; call your string-converter method String not ToString. - ### Avoid Annotations in Comments + Comments do not need extra formatting such as banners of stars. The generated output -may not even be presented in a fixed-width font, so don't depend on spacing for alignment—godoc, -like gofmt, takes care of that. The comments are uninterpreted plain text, so HTML and other -annotations such as _this_ will reproduce verbatim and should not be used. One adjustment godoc -does do is to display indented text in a fixed-width font, suitable for program snippets. +may not even be presented in a fixed-width font, so don't depend on spacing for alignment—godoc, +like gofmt, takes care of that. The comments are uninterpreted plain text, so HTML and other +annotations such as _this_ will reproduce verbatim and should not be used. One adjustment godoc +does do is to display indented text in a fixed-width font, suitable for program snippets. The package comment for the fmt package uses this to good effect. - ### Comment First Word as Subject + Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared. - ### Good Package Name -It's helpful if everyone using the package can use the same name -to refer to its contents, which implies that the package name should -be good: short, concise, evocative. By convention, packages are -given lower case, single-word names; there should be no need for -underscores or mixedCaps. Err on the side of brevity, since everyone -using your package will be typing that name. And don't worry about -collisions a priori. The package name is only the default name for -imports; it need not be unique across all source code, and in the -rare case of a collision the importing package can choose a different -name to use locally. In any case, confusion is rare because the file -name in the import determines just which package is being used. +It's helpful if everyone using the package can use the same name +to refer to its contents, which implies that the package name should +be good: short, concise, evocative. By convention, packages are +given lower case, single-word names; there should be no need for +underscores or mixedCaps. Err on the side of brevity, since everyone +using your package will be typing that name. And don't worry about +collisions a priori. The package name is only the default name for +imports; it need not be unique across all source code, and in the +rare case of a collision the importing package can choose a different +name to use locally. In any case, confusion is rare because the file +name in the import determines just which package is being used. ### Avoid Renaming Imports + Avoid renaming imports except to avoid a name collision; good package names should not require renaming. In the event of collision, prefer to rename the most local or project-specific import. - ### Context as First Argument -Values of the context.Context type carry security credentials, tracing information, -deadlines, and cancellation signals across API and process boundaries. Go programs -pass Contexts explicitly along the entire function call chain from incoming RPCs + +Values of the context.Context type carry security credentials, tracing information, +deadlines, and cancellation signals across API and process boundaries. Go programs +pass Contexts explicitly along the entire function call chain from incoming RPCs and HTTP requests to outgoing requests. Most functions that use a Context should accept it as their first parameter. - ### Do Not Discard Errors -Do not discard errors using _ variables. If a function returns an error, -check it to make sure the function succeeded. Handle the error, return it, or, -in truly exceptional situations, panic. +Do not discard errors using _ variables. If a function returns an error, +check it to make sure the function succeeded. Handle the error, return it, or, +in truly exceptional situations, panic. ### Go Error Format -Error strings should not be capitalized (unless beginning with proper nouns + +Error strings should not be capitalized (unless beginning with proper nouns or acronyms) or end with punctuation, since they are usually printed following other context. That is, use fmt.Errorf("something bad") not fmt.Errorf("Something bad"), -so that log.Printf("Reading %s: %v", filename, err) formats without a spurious +so that log.Printf("Reading %s: %v", filename, err) formats without a spurious capital letter mid-message. This does not apply to logging, which is implicitly line-oriented and not combined inside other messages. - ### Use Crypto Rand -Do not use package math/rand to generate keys, even -throwaway ones. Unseeded, the generator is completely predictable. -Seeded with time.Nanoseconds(), there are just a few bits of entropy. -Instead, use crypto/rand's Reader, and if you need text, print to -hexadecimal or base64 +Do not use package math/rand to generate keys, even +throwaway ones. Unseeded, the generator is completely predictable. +Seeded with time.Nanoseconds(), there are just a few bits of entropy. +Instead, use crypto/rand's Reader, and if you need text, print to +hexadecimal or base64 |