| HN Mirror

Y	Hacker News new \| ask \| show \| jobs

by whoisjuan 1833 days ago

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?:

  // Add a vertical scroll bar
  vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
  add(vScrollBar, BorderLayout.EAST);

Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things:

- It’s creating a visual boundary that aids to the readability of the code. It adds context within a large set of instructions.

- It’s providing context that might not be there for the person who is reading the code. Just because you think the name of that function and what you’re passing into it clearly describes the instruction, doesn’t mean that everyone else does. At least not in a snap. The comment helps to reduce the cognitive load of reading the code because it’s explaining the instruction in plain english.

- The comment itself could be part of a larger narrative that is trying to explain what that file is doing. It’s not there to make the obvious more obvious. It’s there to make the whole file obvious which is evidently important to write readable code.

Look. I know there are purists that get offended with obvious code comments. But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. And sometimes that means explaining in plain english what could be already obvious to you.

People like to think they are writing code like prose that is delightful to the reader, but many times are just writing reader hostile code.

Write code focusing on clarity. Not elegance by obscurity. Make it clear, add structure, add visual boundaries. Ask yourself if what you think is obvious is obvious to everyone. If in doubt explain it with a comment. I’ll rather see an obvious comment and say “well that’s obvious” than spending valuable time trying to understand what certain piece of code is doing.

10 comments

benhoyt 1832 days ago

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)
    }