mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kapil Arya <ka...@mesosphere.io>
Subject Re: Backticks in comments
Date Mon, 02 Nov 2015 19:26:27 GMT
+1 for backticks. Also allows us to differentiate ordinary string literals
like names, etc., from code.

On Mon, Nov 2, 2015 at 2:18 PM, Marco Massenzio <marco@mesosphere.io> wrote:

> +1
>
> I much favor using backticks everywhere for consistency, since (as you
> correctly pointed out) our Doxygen style requires that.
> Hopefully, over time, we will have the whole codebase consistent again
> (also an invite to folks, if you touch the code, to update comments
> accordingly).
>
> BTW - unfortunately, Jira's markdown does not support backticks IIRC, but
> {{ }} to demarcate 'fixed font' in paragraphs (and {code} or {noformat}
> blocks for code snippets).
>
> (RB uses "generally-accepted" markdown, though, so that's good!)
>
> Thanks for raising awareness about this, Greg!
>
> --
> *Marco Massenzio*
> Distributed Systems Engineer
> http://codetrips.com
>
> On Mon, Nov 2, 2015 at 10:38 AM, Alex Clemmer <clemmer.alexander@gmail.com
> >
> wrote:
>
> > +1. Additional note is that this is now the de facto syntax for code
> > snippets on the rest of our tools, too, including RB and JIRA.
> >
> > On Mon, Nov 2, 2015 at 10:32 AM, Greg Mann <greg@mesosphere.io> wrote:
> > > Hey folks!
> > > I wanted to bring up a style issue that I noticed recently. In some
> > > comments in the codebase, backticks are used to quote code excerpts and
> > > object names, while in other comments, single quotes are used. This
> > doesn't
> > > seem to be documented in our style guide (nor in Google's), and I think
> > it
> > > would be a good idea to establish a policy on this and document it, so
> > that
> > > we can avoid wasted review cycles related to this in the future.
> > >
> > > It's likely that the backtick convention began because Doxygen will
> > render
> > > backtick-enclosed text in monospace, and for this reason I would
> propose
> > > that we consistently use backticks to quote code excerpts and object
> > names
> > > in comments from now on. What does everyone else think?
> > >
> > > Cheers,
> > > Greg
> >
> >
> >
> > --
> > Alex
> >
> > Theory is the first term in the Taylor series of practice. -- Thomas M
> > Cover (1992)
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message