Na minha visão você deve tanto documentar "o que" e o "por que".
Claro que o "por que" é muitas vezes mais necessário, mas nem sempre o "o que" é claro de entender apenas olhando o código.

Você pode dizer também que basta limpar o código que o "o que" vai ficar mais claro, mas no mundo real isso nem sempre é viável.
Tem certas coisas que se você limpar demais vai deixar menos flexíveis, mais ruins de manter etc.

Tá aqui um exemplo que estava mexendo agora pouco:
ele nem diz o "por que", porque nesse contexto é meio óbvio, mas o comentário diz o "o que", porque não é algo fácil de notar instantaneamente.

// NewPeerConn stablishes a TCP connection followed by a BitTorrent handshake.
func NewPeerConn(peer Peer, myHs *Handshake) (*PeerConn, error) {
	conn, err := net.DialTimeout("tcp", peer.Address(), 3*time.Second)
	if err != nil {
		return nil, err
	}

	defer conn.SetDeadline(time.Time{})

	conn.SetDeadline(time.Now().Add(5 * time.Second))
	_, err = conn.Write(myHs.Bytes())
	if err != nil {
		return nil, err
	}

	hsBytes := make([]byte, 68)
	_, err = conn.Read(hsBytes)
	if err != nil {
		return nil, err
	}

	conn.SetDeadline(time.Now().Add(5 * time.Second))
	yourHs, err := HandshakeFrom(hsBytes)
	if err != nil {
		return nil, err
	}

	if yourHs.InfoHash != myHs.InfoHash {
		return nil, fmt.Errorf("infoHash do not match. want: %x, got: %x", myHs.InfoHash, yourHs.InfoHash)
	}

	return &PeerConn{
		buf:  make([]byte, 4096),
		peer: peer,
		conn: conn,
		busy: atomic.Bool{},
	}, nil
}