You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@kudu.apache.org by Dan Burkert <da...@apache.org> on 2017/04/10 17:38:35 UTC
Multi-word Flag Style
Hi all,
As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu of
the underscore '_' separator. For example, --memory_limit_hard_bytes can
now be specified as --memory-limit-hard-bytes, or even
--memory_limit-hard_bytes. Of the people I've talked to, most seem to
prefer dashes to underscores in flag names, since that's been the Unix norm
for a long time.
Going forward, I'd like to propose that we document flag names using dashes
wherever possible. We would continue accepting underscores indefinitely,
since to stop doing so would break compatibility. For the most part, this
means incrementally switching the documentation to use dashes, and getting
glog to output dashes in --help output.
Any thoughts?
- Dan
Re: Multi-word Flag Style
Posted by Dan Burkert <da...@apache.org>.
OK it sounds like the consensus is to move to dash-style flags. I've filed
KUDU-1984 <https://issues.apache.org/jira/browse/KUDU-1984> to track this.
I don't have immediate time to work on it, but if no one picks it up I'll
probably circle back when I have less on my plate.
- Dan
On Mon, Apr 10, 2017 at 1:24 PM, Alexey Serbin <as...@cloudera.com> wrote:
> Oops, sure -- we cannot use dashes when referring to the variables in our
> C++ code.
>
>
> On 4/10/17 12:40 PM, Dan Burkert wrote:
>
>> On Mon, Apr 10, 2017 at 11:56 AM, Adar Dembo <ad...@cloudera.com> wrote:
>>
>>> But, I don't know whether gflags can be coerced to programmatically
>>> emit flags with dashes (i.e. when invoked with --help) without a patch
>>> or two.
>>>
>>
>> Yah, I was thinking the same. Gflags just landed support for dashes
>> upstream in 2.2, so I imagine they would be open to a patch to configure
>> dashes in help output.
>>
>>
>> Certainly in the code we would want to retain the use of
>>> underscores when referring to flag variables; FLAGS_foo_bar conforms
>>> to our coding style more than something like FLAGS-foo-bar.
>>>
>>> I agree - I don't think dashes are valid identifier characters in C++
>> anyway.
>>
>> - Dan
>>
>>
>>
>>> On Mon, Apr 10, 2017 at 11:00 AM, Alexey Serbin <as...@cloudera.com>
>>> wrote:
>>>
>>>> I think it's a good move. It would be nice to add a notice about that
>>>> in
>>>> the user-facing docs.
>>>>
>>>> Also, I think it would be more consistent to convert those flags
>>>>
>>> altogether
>>>
>>>> at some point to be in dash-ish form, both the code and the docs.
>>>> Maybe,
>>>> 1.4 is a good point to do that.
>>>>
>>>>
>>>> Kind regards,
>>>>
>>>> Alexey
>>>>
>>>>
>>>>
>>>> On 4/10/17 10:42 AM, William Berkeley wrote:
>>>>
>>>>> I agree, for the reason you gave: dashes are the norm in Unix, so they
>>>>> "feel right" for flag names.
>>>>>
>>>>> -Will
>>>>>
>>>>> On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org>
>>>>> wrote:
>>>>>
>>>>> Hi all,
>>>>>>
>>>>>> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu
>>>>>>
>>>>> of
>>>
>>>> the underscore '_' separator. For example, --memory_limit_hard_bytes
>>>>>> can
>>>>>> now be specified as --memory-limit-hard-bytes, or even
>>>>>> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
>>>>>> prefer dashes to underscores in flag names, since that's been the Unix
>>>>>> norm
>>>>>> for a long time.
>>>>>>
>>>>>> Going forward, I'd like to propose that we document flag names using
>>>>>> dashes
>>>>>> wherever possible. We would continue accepting underscores
>>>>>>
>>>>> indefinitely,
>>>
>>>> since to stop doing so would break compatibility. For the most part,
>>>>>>
>>>>> this
>>>
>>>> means incrementally switching the documentation to use dashes, and
>>>>>> getting
>>>>>> glog to output dashes in --help output.
>>>>>>
>>>>>> Any thoughts?
>>>>>>
>>>>>> - Dan
>>>>>>
>>>>>>
>
Re: Multi-word Flag Style
Posted by Alexey Serbin <as...@cloudera.com>.
Oops, sure -- we cannot use dashes when referring to the variables in
our C++ code.
On 4/10/17 12:40 PM, Dan Burkert wrote:
> On Mon, Apr 10, 2017 at 11:56 AM, Adar Dembo <ad...@cloudera.com> wrote:
>> But, I don't know whether gflags can be coerced to programmatically
>> emit flags with dashes (i.e. when invoked with --help) without a patch
>> or two.
>
> Yah, I was thinking the same. Gflags just landed support for dashes
> upstream in 2.2, so I imagine they would be open to a patch to configure
> dashes in help output.
>
>
>> Certainly in the code we would want to retain the use of
>> underscores when referring to flag variables; FLAGS_foo_bar conforms
>> to our coding style more than something like FLAGS-foo-bar.
>>
> I agree - I don't think dashes are valid identifier characters in C++
> anyway.
>
> - Dan
>
>
>>
>> On Mon, Apr 10, 2017 at 11:00 AM, Alexey Serbin <as...@cloudera.com>
>> wrote:
>>> I think it's a good move. It would be nice to add a notice about that in
>>> the user-facing docs.
>>>
>>> Also, I think it would be more consistent to convert those flags
>> altogether
>>> at some point to be in dash-ish form, both the code and the docs. Maybe,
>>> 1.4 is a good point to do that.
>>>
>>>
>>> Kind regards,
>>>
>>> Alexey
>>>
>>>
>>>
>>> On 4/10/17 10:42 AM, William Berkeley wrote:
>>>> I agree, for the reason you gave: dashes are the norm in Unix, so they
>>>> "feel right" for flag names.
>>>>
>>>> -Will
>>>>
>>>> On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org>
>>>> wrote:
>>>>
>>>>> Hi all,
>>>>>
>>>>> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu
>> of
>>>>> the underscore '_' separator. For example, --memory_limit_hard_bytes
>>>>> can
>>>>> now be specified as --memory-limit-hard-bytes, or even
>>>>> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
>>>>> prefer dashes to underscores in flag names, since that's been the Unix
>>>>> norm
>>>>> for a long time.
>>>>>
>>>>> Going forward, I'd like to propose that we document flag names using
>>>>> dashes
>>>>> wherever possible. We would continue accepting underscores
>> indefinitely,
>>>>> since to stop doing so would break compatibility. For the most part,
>> this
>>>>> means incrementally switching the documentation to use dashes, and
>>>>> getting
>>>>> glog to output dashes in --help output.
>>>>>
>>>>> Any thoughts?
>>>>>
>>>>> - Dan
>>>>>
Re: Multi-word Flag Style
Posted by Dan Burkert <da...@apache.org>.
On Mon, Apr 10, 2017 at 11:56 AM, Adar Dembo <ad...@cloudera.com> wrote:
>
> But, I don't know whether gflags can be coerced to programmatically
> emit flags with dashes (i.e. when invoked with --help) without a patch
> or two.
Yah, I was thinking the same. Gflags just landed support for dashes
upstream in 2.2, so I imagine they would be open to a patch to configure
dashes in help output.
> Certainly in the code we would want to retain the use of
> underscores when referring to flag variables; FLAGS_foo_bar conforms
> to our coding style more than something like FLAGS-foo-bar.
>
I agree - I don't think dashes are valid identifier characters in C++
anyway.
- Dan
>
>
> On Mon, Apr 10, 2017 at 11:00 AM, Alexey Serbin <as...@cloudera.com>
> wrote:
> > I think it's a good move. It would be nice to add a notice about that in
> > the user-facing docs.
> >
> > Also, I think it would be more consistent to convert those flags
> altogether
> > at some point to be in dash-ish form, both the code and the docs. Maybe,
> > 1.4 is a good point to do that.
> >
> >
> > Kind regards,
> >
> > Alexey
> >
> >
> >
> > On 4/10/17 10:42 AM, William Berkeley wrote:
> >>
> >> I agree, for the reason you gave: dashes are the norm in Unix, so they
> >> "feel right" for flag names.
> >>
> >> -Will
> >>
> >> On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org>
> >> wrote:
> >>
> >>> Hi all,
> >>>
> >>> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu
> of
> >>> the underscore '_' separator. For example, --memory_limit_hard_bytes
> >>> can
> >>> now be specified as --memory-limit-hard-bytes, or even
> >>> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
> >>> prefer dashes to underscores in flag names, since that's been the Unix
> >>> norm
> >>> for a long time.
> >>>
> >>> Going forward, I'd like to propose that we document flag names using
> >>> dashes
> >>> wherever possible. We would continue accepting underscores
> indefinitely,
> >>> since to stop doing so would break compatibility. For the most part,
> this
> >>> means incrementally switching the documentation to use dashes, and
> >>> getting
> >>> glog to output dashes in --help output.
> >>>
> >>> Any thoughts?
> >>>
> >>> - Dan
> >>>
> >
>
Re: Multi-word Flag Style
Posted by Adar Dembo <ad...@cloudera.com>.
+1 to referring to gflags with dashes instead of underscores in Kudu docs.
But, I don't know whether gflags can be coerced to programmatically
emit flags with dashes (i.e. when invoked with --help) without a patch
or two. Certainly in the code we would want to retain the use of
underscores when referring to flag variables; FLAGS_foo_bar conforms
to our coding style more than something like FLAGS-foo-bar.
On Mon, Apr 10, 2017 at 11:00 AM, Alexey Serbin <as...@cloudera.com> wrote:
> I think it's a good move. It would be nice to add a notice about that in
> the user-facing docs.
>
> Also, I think it would be more consistent to convert those flags altogether
> at some point to be in dash-ish form, both the code and the docs. Maybe,
> 1.4 is a good point to do that.
>
>
> Kind regards,
>
> Alexey
>
>
>
> On 4/10/17 10:42 AM, William Berkeley wrote:
>>
>> I agree, for the reason you gave: dashes are the norm in Unix, so they
>> "feel right" for flag names.
>>
>> -Will
>>
>> On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org>
>> wrote:
>>
>>> Hi all,
>>>
>>> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu of
>>> the underscore '_' separator. For example, --memory_limit_hard_bytes
>>> can
>>> now be specified as --memory-limit-hard-bytes, or even
>>> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
>>> prefer dashes to underscores in flag names, since that's been the Unix
>>> norm
>>> for a long time.
>>>
>>> Going forward, I'd like to propose that we document flag names using
>>> dashes
>>> wherever possible. We would continue accepting underscores indefinitely,
>>> since to stop doing so would break compatibility. For the most part, this
>>> means incrementally switching the documentation to use dashes, and
>>> getting
>>> glog to output dashes in --help output.
>>>
>>> Any thoughts?
>>>
>>> - Dan
>>>
>
Re: Multi-word Flag Style
Posted by Alexey Serbin <as...@cloudera.com>.
I think it's a good move. It would be nice to add a notice about that
in the user-facing docs.
Also, I think it would be more consistent to convert those flags
altogether at some point to be in dash-ish form, both the code and the
docs. Maybe, 1.4 is a good point to do that.
Kind regards,
Alexey
On 4/10/17 10:42 AM, William Berkeley wrote:
> I agree, for the reason you gave: dashes are the norm in Unix, so they
> "feel right" for flag names.
>
> -Will
>
> On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org> wrote:
>
>> Hi all,
>>
>> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu of
>> the underscore '_' separator. For example, --memory_limit_hard_bytes can
>> now be specified as --memory-limit-hard-bytes, or even
>> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
>> prefer dashes to underscores in flag names, since that's been the Unix norm
>> for a long time.
>>
>> Going forward, I'd like to propose that we document flag names using dashes
>> wherever possible. We would continue accepting underscores indefinitely,
>> since to stop doing so would break compatibility. For the most part, this
>> means incrementally switching the documentation to use dashes, and getting
>> glog to output dashes in --help output.
>>
>> Any thoughts?
>>
>> - Dan
>>
Re: Multi-word Flag Style
Posted by William Berkeley <wd...@cloudera.com>.
I agree, for the reason you gave: dashes are the norm in Unix, so they
"feel right" for flag names.
-Will
On Mon, Apr 10, 2017 at 1:38 PM, Dan Burkert <da...@apache.org> wrote:
> Hi all,
>
> As of Kudu 1.3, multi-word flags can use a dash '-' separator in lieu of
> the underscore '_' separator. For example, --memory_limit_hard_bytes can
> now be specified as --memory-limit-hard-bytes, or even
> --memory_limit-hard_bytes. Of the people I've talked to, most seem to
> prefer dashes to underscores in flag names, since that's been the Unix norm
> for a long time.
>
> Going forward, I'd like to propose that we document flag names using dashes
> wherever possible. We would continue accepting underscores indefinitely,
> since to stop doing so would break compatibility. For the most part, this
> means incrementally switching the documentation to use dashes, and getting
> glog to output dashes in --help output.
>
> Any thoughts?
>
> - Dan
>