Hi All,

As discussed it makes sense to comment our code so that we go docs can be generated from them. Documentation re go doc comments seem to be sparse, but there is a lot of overlap that can be drawn from similar code-generated docs like javadoc.

From my reading specifically re go doc I would suggest we adopt a practice of commenting our code like the below. All feedback welcome, but let’s settle on one way of doing this so we can be consistent across the team. So if anyone has suggested alternatives, please raise them in this thread so can can agree & move on to implementing them in our code.

I think [this blog post|https://elliot.land/post/godoc-tips-tricks] covers the mechanics of how to comment key elements of our code, such as variables, methods and packages. It also covers how to add paragraphs, headings/ titles, and code samples to the go doc comment. I won’t try to summarise it here, and suggest reading it and treating it as a reference.

Examples of good comments don’t seem so common, but below are some I did come across:

Good package comment example:

/*

->TAB Package TraceLog implements a file based logging.

->TAB The programmer should feel free to tace log as much of the code.

->CRLF

->TAB New Parameters

->CRLF

->TAB The following is a list of parameters for creating a TraceLog:

      ->TAB baseFilePath: The base location to store all log directories.

      ->TAB machineName: The name of the machine or system. Information is used.

      ->TAB writeToStdout: Set to True if you want the system to also write.

->CRLF

->TAB TraceLog File Management

->CRLF

->TAB Every 2 minutes TraceLog will check each open file for two conditions:

->CRLF

      ->TAB 1. Has a message been written to the file within the last 2 minutes.

      ->TAB 2. Is the size of the file greater than 10 Meg.

*/

package tracelog

I didn’t find anything easily that illustrates good method comments in go doc and mainly resorted to checking [how larger go repos handle go doc comments|https://github.com/golang/go/blob/master/src/text/scanner/scanner.go] so if anyone has any good examples, perhaps they can flag them and we can standardise,

Damien

Looking at the go std lib is always a good idea for getting an understanding of best practices. All the Go documentation is generated from comments in the code. 

As a general rule. You should always comment exported methods/functions from a package as this is your exposed API. You can then have a package level comment also. See example https://github.com/golang/go/blob/master/src/sort/sort.go