Mailing-List: contact dev-help@mesos.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@mesos.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAD2Zrn1i+pY4Odv=GWXa5=X2jPbsNn9r=OQ+tuV+SHLvbpvhfA@mail.gmail.com>
References: 
 <CAMvp0pSqsQ5tM2CQ2uqQTr+hOwYquoaGeC13XWNTJ45q6jSQPw@mail.gmail.com>
 <CACYWy82V9+5x9BosqzGvOk_1QDZ9kLKnjmThN3Okt09jkriHoQ@mail.gmail.com>
 <CAD2Zrn1i+pY4Odv=GWXa5=X2jPbsNn9r=OQ+tuV+SHLvbpvhfA@mail.gmail.com>
From: Kapil Arya <kapil@mesosphere.io>
Date: Mon, 2 Nov 2015 14:26:27 -0500
Message-ID: 
 <CA+fJHLh19d+of98AzJ_BQ=awem=+--GDgjMt0uQ63cwUNNY4uQ@mail.gmail.com>
Subject: Re: Backticks in comments
To: dev <dev@mesos.apache.org>
Content-Type: multipart/alternative; boundary=001a113d636813e50e052393c2ea

--001a113d636813e50e052393c2ea
Content-Type: text/plain; charset=UTF-8

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

--001a113d636813e50e052393c2ea--