Canonical comments as budget code snippets

Written by Darren Bruning on
Canonical comments as budget code snippets

Every application has “cross-cutting concerns” - things that are repeated throughout the app, such as:

  • API access
  • Database access
  • Logging

Generally whenever we see repetition, we want to reach for an abstraction. But some things that are repeated are so low-level that we can’t (or shouldn’t) abstract them. Sometimes it’s just the way we want to structure a small code block, e.g. to handle errors in an application, or conventions around logging format.

Many IDE’s have a “code snippets” feature to help with this, but I’ve never adopted that. Probably I’m just too lazy if I’m being honest.

I’ve started putting a comment in code for the “canonical” example of these things. Then when I’m coding and I need to e.g. do an API call, I can search the codebase for “Canonical:” and navigate straight to my “best-in-class" example of how to do an API call.

Bonus points for using a JetBrains IDE, which has great search generally and the “preview” window so I can just copy & paste out the canonical example without even having to navigate to that file.