Why does the macros of the family DEFINE_<data_type>(name, default_val, doc) in commandlineflags.h have the "doc" argument ?

18 views
Skip to first unread message

Sayan Bhattacharjee

unread,
Aug 16, 2019, 1:02:44 PM8/16/19
to benchmark-discuss
Hi,

I've been enjoying benchmark because it is an awesome tool! 

I've been trying to understand the code base and something stood out to me.



In the file, "commandlineflags.h" from line 18 to 23 we have the macros of the family :

#DEFINE_<data_type>(name, default_val, doc)

Where, <data_type> is one of bool, int32, int64, double, string

I have included a picture (benchmark-1.png) of the macros I'm currently interested in.



The data in "doc" is clearly not being used and from the second picture (benchmark-2.png) it looks like the
doc argument could have easily been a multi line comment and that would have been much more "clean".



The question I have is, Why is the "doc" argument present in the macro argument list?



The only two reasons I can think of are, to either ensure that the developer provides a documentation string or
there is plan to use the "doc" argument in future for something more advanced.

This is very interesting ...
.
Thanks

benchmark-1.png
benchmark-2.png

Dominic Hamon

unread,
Aug 20, 2019, 10:01:41 AM8/20/19
to Sayan Bhattacharjee, benchmark-discuss
That's a really good spot. The short answer is: because this is how we define them at Google. However, we didn't do the full integration because we had a very simple use-case for our flags.

We could remove the doc field. We could also (my longer-term preference) start using abseil across the library and use their flags.


--
You received this message because you are subscribed to the Google Groups "benchmark-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to benchmark-disc...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/benchmark-discuss/2331e658-7489-4480-bc15-8562ecfdd1c0%40googlegroups.com.

Sayan Bhattacharjee

unread,
Aug 21, 2019, 7:45:43 AM8/21/19
to benchmark-discuss
Dominic Hamon,

Using grep I found only 12 use cases of the macros and they are all in benchmark.cc.

Removing the doc argument will require change to two files and shouldn't have any repercussions.

Should I raise an issue and send a pull request for the modifications?

Thanks
~Sayan

On Tuesday, August 20, 2019 at 7:31:41 PM UTC+5:30, Dominic Hamon wrote:
That's a really good spot. The short answer is: because this is how we define them at Google. However, we didn't do the full integration because we had a very simple use-case for our flags.

We could remove the doc field. We could also (my longer-term preference) start using abseil across the library and use their flags.


On Fri, Aug 16, 2019 at 6:02 PM Sayan Bhattacharjee <aero...@gmail.com> wrote:
Hi,

I've been enjoying benchmark because it is an awesome tool! 

I've been trying to understand the code base and something stood out to me.



In the file, "commandlineflags.h" from line 18 to 23 we have the macros of the family :

#DEFINE_<data_type>(name, default_val, doc)

Where, <data_type> is one of bool, int32, int64, double, string

I have included a picture (benchmark-1.png) of the macros I'm currently interested in.



The data in "doc" is clearly not being used and from the second picture (benchmark-2.png) it looks like the
doc argument could have easily been a multi line comment and that would have been much more "clean".



The question I have is, Why is the "doc" argument present in the macro argument list?



The only two reasons I can think of are, to either ensure that the developer provides a documentation string or
there is plan to use the "doc" argument in future for something more advanced.

This is very interesting ...
.
Thanks

--
You received this message because you are subscribed to the Google Groups "benchmark-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to benchmar...@googlegroups.com.

Dominic Hamon

unread,
Aug 21, 2019, 11:00:12 AM8/21/19
to Sayan Bhattacharjee, benchmark-discuss
Please do!


To unsubscribe from this group and stop receiving emails from it, send an email to benchmark-disc...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/benchmark-discuss/fcfbfac3-cd59-4aa5-a2a4-7112ece2c5ed%40googlegroups.com.
Reply all
Reply to author
Forward
0 new messages