Documentation of an exported function should start with the function’s name GO-D5001
Documentation
Minor
a year ago
—
a year old
comment on exported function ServeFile should be of the form "ServeFile ..."
9 "github.com/gorilla/mux"
10)
11
12// func ServeFile() handles requests to serve a particular file. 13// It takes a ResponseWriter (w) and a Request (r) as arguments.
14func ServeFile(w http.ResponseWriter, r *http.Request) {
15 // extract the "id" parameter from the URLcomment on exported function Bubble_sort should be of the form "Bubble_sort ..."
1package Alg_for_array
2
3// All sorted 4func Bubble_sort(array []int) { // bubble sort
5 for i := 0; i < len(array); i++ {
6 for j := 0; j < len(array)-1; j++ {comment on exported function Sum should be of the form "Sum ..."
5 "time"
6)
7
8// The Sum function takes an array of integers and returns the sum of all the numbers in the array. 9// The array is defined in the main function and passed to the Sum function.
10func Sum(array []int) int {
11 sum := 0
Description
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.
If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep.
See https://golang.org/doc/effective_go.html#commentary for more information on how to write good documentation.
Bad practice
package main
// This function tries to summon a cybernetically enhanced duck
func SummonDucks() {
}
Recommended
package main
// SummonDucks tries to summon a cybernetically enhanced duck
func SummonDucks() {
}