[cmake-developers] Questions about coding conventions

[Brad King]

On 06/10/2016 05:43 PM, Daniel Pfeifer wrote:
>> Please look at documenting this in CONTRIBUTING.rst once we resolve
>> this discussion.
> 
> ok.

+1 to Steve's suggestion of putting it in cmake-developer(7).

>>> So far it is pretty consistent. But how to name free functions and
>>> macros? I have seen all kinds of variations.
>>
>> No convention was ever established for those.
> 
> I see. Any strong opinion whether a convention should be established?
> I would assume UPPER_CASE for macros. Any prefix?
> Any opinions about free functions?

IIRC several existing macros use the CMAKE_ prefix and are named
all upper-case.  I think that or CM_ would be fine.

For free functions I think naming them as cmCamelCase just like classes
has been done in a few places.

> So the convention would be to use `std::string` or
> `cmOptional<std::string>` as return values.

Yes, though I think we should wait for this change until other pending
cleanups are done.

> Should `std::string const&` be allowed as return value?

I like value semantics but IIRC we tried to replace some "getters"
that currently return std::string by reference with values and it
showed up in profiling for heavily-called getters.

> Arguments should be preferred as `const&` I assume.

Yes.

> Some other questions:
> 
> Can't `std::ifstream` and `std::ofstream` be used directly? It seams
> that kwsys does some workarounds

Yes, std::{o,f}stream can be used directly.  KWSys may have some old
workarounds that haven't been fully removed yet.

> I see that `#include <string.h>` is preferred over `#include
> <cstring>`. Are there old compilers supported that prohibit the latter
> or was it just not changed yet?

The dashboard will tell us.  As Steve said I think these are legacy.

> cmStandardIncludes.h includes many standard headers. That is against
> the idea of include-what-you-use. Is there a particular requirement or
> was it just not cleaned up yet?

We need cmsys/Configure.h to be the first file in every C++ translation
unit.  Also cmStandardIncludes.h used to have workarounds for system
headers on old platforms.  These days we can probably clean this up,
especially with tools like include-what-you-use.

> Should we begin using newer language features optionally by providing
> macros like CM_OVERRIDE?

Let's start with just CM_OVERRIDE.  We have a lot of virtual methods
and overrides so that will be a nice cleanup.  It will also be a test
case for initial introduction of the infrastructure needed to optionally
use C++11 features.

Thanks,
-Brad