This is the mail archive of the
mailing list for the GCC project.
Re: style convention: /*foo_p=*/ to annotate bool arguments
On 10/05/2016 05:12 PM, Jeff Law wrote:
> On 10/04/2016 03:08 PM, Jason Merrill wrote:
>> On Tue, Oct 4, 2016 at 4:29 PM, Zan Lynx <email@example.com> wrote:
>>> On 10/04/2016 02:00 PM, Martin Sebor wrote:
>>>> This would have been easier if C++ had allowed the same default
>>>> value to
>>>> be given in both the declaration and the definition:
>>>> void foo(int x, int y, bool bar_p = false);
>>>> void foo(int x, int y, bool bar_p = false)
>>> There is really no point to duplicating it. The default value goes into
>>> the headers which is what is read by users of the code.
>> In GCC sources, I think users look at the function definition more
>> often than the declaration in the header, the latter of which
>> typically has neither comments nor parameter names.
> So true. One could claim that our coding standards made a fundamental
> mistake -- by having all the API documentation at the implementation
> rather than at the declaration. Sigh....
It's never too late. GDB used to be like that, and a few
years ago we've decided to start putting comments in the headers instead. We
haven't done a mass conversion. Simply new extern functions
get documented at the declaration instead of implementation, and we
also generally move the comment when we're making a static function
extern. Over time, old code is moved around or rewritten, and
comments migrate to API headers. I think that has been a good idea.
Particularly more so for headers defining some module's public API.