•

Naming Functions: When Intent and Implementation Differ

https://chrisoldwood.blogspot.com/2024/04/naming-functions-when-intent-and.html

Tales of a computer programmer.

5 comments

DrDeadCrash

•

I would use reportMissingData

bravesilvernest

•

See, both report and record signify different things in my mind. The original code was just printing to stdout.

In my mind logMissingData makes more sense because it's not actively sending anything; it's just logging.

DrDeadCrash

•

I agree that report and record are different. To me record means it's preserved in some managed way.

The implementation has the ability to vary quite widely from simply printing to stdout, logging to a file, writing to a queue / database, and yet the same name will continue to reflect all those possibilities

This makes it sound like the intent goes beyond logging, but not so far as recording. That's how I come to 'report' as the correct verb.

otl

•

I would use reportMissingData

Agreed, report feels clearer as the verb "record" is more about permanent storage and later reference.

Or even just reportMissing? Depending on what's happening around call sites, I often find I can drop generic stuff like "Data" and it's just as clear, especially when looking at a function signature. For instance:

func reportMissing(data) { ... }

arendjr

•

I can’t say for sure we won’t need to revisit this again as we learn more about the nature of what data is missing and whether with more context we can automatically triage and notify the right people, but for now it feels like the cost / benefit ratio of “talking versus doing” is about right.

This was a nice post, and I agree people should think a bit about how to name things, because getting it wrong can lead to others making wrong assumptions, which ends up wasting a lot of time.

That said, I would get pretty annoyed if a PR I’m involved with ended up with this level of bike-shedding over a function name. If the end goal is to avoid wasting people’s time, bringing out the big guns and making three attempts, with three rounds of review, to get the name of such a trivial function right is surely throwing out the cost / benefit ratio right upfront.