CODEWITHSUNDEEP
commentsconventionscode-standards
Oliver Scase
Oliver Scase

Reputation: 106

Does a named standard exist for comment annotations?

I have encountered, and used, several different forms of comment annotations. Eg.

// TODO: Also trigger this task
// FIXME: in this very specific circumstance this should handle this way instead
// NOTE: This is important for this specific case

Do any named conventions or standards exist in regards to this?

I've seen different approaches with variations including:

  1. The exact annotation names that are permissible (eg. sometime people use "PERF", "HACK", "WARN", etc.)
  2. The format of these (FIXME: [message], fixme - [message]
  3. Including task IDs (and how these should be denoted)

From my experience, it has come down very much to a standard of precedence within a team:

We've always used these annotations in this format, so that's how you should too

This is a good start - a standard is better than no standard. However, its a very opinionated standard and unclear in the accepted implementation. I was wondering whether there were any named conventions and guidelines one could reference to assist in the onboarding of new team members, and the automated linting of code?

NOTE: I appreciate that there is some level of controversy regarding whether these types of comments should/should not be used, however that is not within the scope of this question.

Upvotes: 0

Views: 16

Answers (0)

Related Questions