Yeah, I like the "visual boundaries" way of framing it. A line of whitespace is a visual boundary, of course, but I find the // comment above it acts as a heading. Like a bold heading above a couple of paragraphs of text in a document.

I wouldn't add a heading above every paragraph, but I would might above every few paragraphs. In code, this translates to every 5-15 lines of code. Here's some code I wrote recently that shows this (https://github.com/canonical/pebble/blob/b152ff448bbe7d08c39...):

    func writeFile(item writeFilesItem, source io.Reader) error {
        if !pathpkg.IsAbs(item.Path) {
            return nonAbsolutePathError(item.Path)
        }

        // Create parent directory if needed
        if item.MakeDirs {
            err := os.MkdirAll(pathpkg.Dir(item.Path), 0o755)
            if err != nil {
                return fmt.Errorf("cannot create directory: %w", err)
            }
        }

        // Atomically write file content to destination.
        perm, err := parsePermissions(item.Permissions, 0o644)
        if err != nil {
            return err
        }
        uid, gid, err := normalizeUidGid(item.UserID, item.GroupID, item.User, item.Group)
        if err != nil {
            return fmt.Errorf("cannot look up user and group: %w", err)
        }
        sysUid, sysGid := sys.UserID(osutil.NoChown), sys.GroupID(osutil.NoChown)
        if uid != nil && gid != nil {
            sysUid, sysGid = sys.UserID(*uid), sys.GroupID(*gid)
        }
        return atomicWriteChown(item.Path, source, perm, 0, sysUid, sysGid)
    }