// Package main demonstrates best practices for Go comments.
//
// The package comment should introduce the package and provide
// a high-level overview. It appears first in the godoc output.
package main

import "fmt"

// User represents a system user.
//
// Doc comments for types should start with the type name.
type User struct {
    ID   int
    Name string
}

// NewUser creates a user with the given ID and name.
//
// Doc comments for functions should be complete sentences
// starting with the function name. This allows godoc to
// extract them for summaries.
func NewUser(id int, name string) *User {
    return &User{ID: id, Name: name}
}

// UpdateName changes the user's display name.
//
// Deprecated: Use UpdateProfile instead. This method will be
// removed in v2.0.
func (u *User) UpdateName(newName string) {
    u.Name = newName
}

func main() {
    // Line comments explain the "why", not the "what".
    // Bad:  i++ // Increment i
    // Good: i++ // Skip the CSV header row
    
    u := NewUser(1, "Alice")
    
    // TODO(jdoe): Refactor this to use the new database API.
    // TODOs often include a username and context.
    fmt.Println("User:", u.Name)
    
    // Directives are special comments for tools.
    // They must start at the beginning of the line (no spaces).
    //go:noinline
    _ = func() { fmt.Println("I won't be inlined") }
}