This post is a follow up to Friday’s post on comments in Go.

Keith Rarick and Nate Finch pointed out that I had neglected to include two important practical use cases.

Build tags

I’ve previously written about how to use // +build tags to perform conditional compilation. In light of the previous post it’s probably worth recapping them here.

• Build tags must use the // form.

  // +build right
  /* +build wrong */

• Build tags must be their own comment, they must not be associated with a declaration.

  // Copyright Microsoft 1981
  
  // +build !darwin
  
  // Package basic implements Dartmouth's BASIC interpreter.  
  package basic

• Build tags must occur early in the file. Only the first few lines of the file are scanned when filtering files by build tags.

  package wrong
  
  import "io"
  
  // +build whoops too,late

Copyright headers

The second is managing procedural issues if your licence requires you to include a copyright block at the top of source.

This was also briefly covered in the conditional compilation article. To recap

• Most licences that recommend copyright headers require them to be at the top of the file, this means they must come before a package declaration, and its comment.
• You probably don’t want the copyright header being part of your godoc, so the comment block holding the copyright header and the package declaration should be separated by a newline.
• If you have any build tags, they should also appear between the copyright block and the package declaration. As all three are separate comment, they should be separated by a newline.

  // Copyright Commodore Inc, 1982
  
  // +build 6502
  
  // Package c64 is the computer for the masses, not the classes.
  package c64

• If this leads to a verbose combination of copyright header, build tag, and package comment for godoc, consider moving the comment on the package declaration to a separate file. This is traditionally named doc.go and contains only the package declaration and its commentary.