You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mesos.apache.org by Greg Mann <gr...@mesosphere.io> on 2015/11/02 19:32:14 UTC
Backticks in comments
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
Re: Backticks in comments
Posted by Greg Mann <gr...@mesosphere.io>.
Hello everyone!
FYI, here's the review for the backtick style guide change:
https://reviews.apache.org/r/40367/
Greg
On Fri, Nov 6, 2015 at 7:55 AM, Greg Mann <gr...@mesosphere.io> wrote:
> Thanks for the input y'all, sounds like we have a general consensus for
> backticks in comments to enclose code excerpts and object names. I'll
> submit a patch to change the style guide and make it official.
>
> Cheers,
> Greg
>
> On Fri, Nov 6, 2015 at 4:46 AM, Alexander Rojas <al...@mesosphere.io>
> wrote:
>
>> +1 for backticks!
>>
>> > On 02 Nov 2015, at 19:32, Greg Mann <gr...@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
>>
>>
>
Re: Backticks in comments
Posted by Greg Mann <gr...@mesosphere.io>.
Thanks for the input y'all, sounds like we have a general consensus for
backticks in comments to enclose code excerpts and object names. I'll
submit a patch to change the style guide and make it official.
Cheers,
Greg
On Fri, Nov 6, 2015 at 4:46 AM, Alexander Rojas <al...@mesosphere.io>
wrote:
> +1 for backticks!
>
> > On 02 Nov 2015, at 19:32, Greg Mann <gr...@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
>
>
Re: Backticks in comments
Posted by Alexander Rojas <al...@mesosphere.io>.
+1 for backticks!
> On 02 Nov 2015, at 19:32, Greg Mann <gr...@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
Re: Backticks in comments
Posted by Adam Bordelon <ad...@mesosphere.io>.
+1 Make it so.
On Wed, Nov 4, 2015 at 7:31 AM, haosdent <ha...@gmail.com> wrote:
> +1 Backticks used in markdown widely.
>
> On Wed, Nov 4, 2015 at 11:03 PM, Bernd Mathiske <be...@mesosphere.io>
> wrote:
>
> > +1
> >
> > > On Nov 2, 2015, at 8:34 PM, Isabel Jimenez <
> > contact.isabeljimenez@gmail.com> wrote:
> > >
> > > +1 for backticks, same comment as Kapil, really nice to be able to
> make a
> > > difference from string literals.
> > >
> > > On Mon, Nov 2, 2015 at 11:26 AM, Kapil Arya <ka...@mesosphere.io>
> wrote:
> > >
> > >> +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 <ma...@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 <gr...@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)
> > >>>>
> > >>>
> > >>
> >
> >
>
>
> --
> Best Regards,
> Haosdent Huang
>
Re: Backticks in comments
Posted by haosdent <ha...@gmail.com>.
+1 Backticks used in markdown widely.
On Wed, Nov 4, 2015 at 11:03 PM, Bernd Mathiske <be...@mesosphere.io> wrote:
> +1
>
> > On Nov 2, 2015, at 8:34 PM, Isabel Jimenez <
> contact.isabeljimenez@gmail.com> wrote:
> >
> > +1 for backticks, same comment as Kapil, really nice to be able to make a
> > difference from string literals.
> >
> > On Mon, Nov 2, 2015 at 11:26 AM, Kapil Arya <ka...@mesosphere.io> wrote:
> >
> >> +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 <ma...@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 <gr...@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)
> >>>>
> >>>
> >>
>
>
--
Best Regards,
Haosdent Huang
Re: Backticks in comments
Posted by Bernd Mathiske <be...@mesosphere.io>.
+1
> On Nov 2, 2015, at 8:34 PM, Isabel Jimenez <co...@gmail.com> wrote:
>
> +1 for backticks, same comment as Kapil, really nice to be able to make a
> difference from string literals.
>
> On Mon, Nov 2, 2015 at 11:26 AM, Kapil Arya <ka...@mesosphere.io> wrote:
>
>> +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 <ma...@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 <gr...@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)
>>>>
>>>
>>
Re: Backticks in comments
Posted by Isabel Jimenez <co...@gmail.com>.
+1 for backticks, same comment as Kapil, really nice to be able to make a
difference from string literals.
On Mon, Nov 2, 2015 at 11:26 AM, Kapil Arya <ka...@mesosphere.io> wrote:
> +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 <ma...@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 <gr...@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)
> > >
> >
>
Re: Backticks in comments
Posted by Kapil Arya <ka...@mesosphere.io>.
+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 <ma...@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 <gr...@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)
> >
>
Re: Backticks in comments
Posted by Marco Massenzio <ma...@mesosphere.io>.
+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 <cl...@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 <gr...@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)
>
Re: Backticks in comments
Posted by Alex Clemmer <cl...@gmail.com>.
+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 <gr...@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)