You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Masaori Koshiba <ma...@apache.org> on 2019/05/13 01:57:00 UTC
[PROPOSAL] Remove P_ or I_ naming convention for header files
We have a naming convention for header files, P_ or I_ prefix. Details are
described in below.
> # Header files
> In most subsystems, header files are named with a P_ or I_ prefix. P_
files should contain
> any types and definitions that are private to the subsystem, while the
public interface
> should be contained in a I_-prefixed header.
https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
But this looks obsoleted 1). many subsystem don't follow this rule, 2).
even if this rule is
followed, P_ files (subsystem private header files) are included from out
side of subsystem.
(e.g. P_Net.h, P_EventSystem.h )
The consensus at last summit was we should remove this rule.
If there’re any real use case of subsystem private header files, we can
move them a directory
under the subsystem and include them internally.
Any thoughts?
Thanks,
Masaori
Re: [PROPOSAL] Remove P_ or I_ naming convention for header files
Posted by Bryan Call <bc...@apache.org>.
+1
-Bryan
> On May 13, 2019, at 5:33 PM, Masaori Koshiba <ma...@apache.org> wrote:
>
>> I’m pretty -1 on having files with the same filenames in different
> location. I’m sure that will just break all sort of shit, including my tiny
> brain.
> I strongly agree with this.
>
>> I’m leaning more towards Chao's proposal of cleaning up the actual mess.
> If we want to rename the I_ and P_ files, that’s fine too.
> We should figure out why the P_ files are needed. It looks like we don't
> need them in many cases.
>
>> We moved some stuff to a generic include directory, such that we can get
> away with just one single -I${topdir)/include in the compiles, and then use
> #include “some_major_module/P_Stuff.h”.
> Looks reasonable. I think I_Stuff.h or Stuff.h instead P_Stuff.h.
>
> In total, using I_/P_Net.h for example, if we really need private header
> file by some reason, the change would be like this?
>
> # before
> /iocore/net/I_Net.h
> /iocore/net/P_Net.h
>
> - include search path : ${topdir)/iocore/net
> - #include "P_Net.h" and #include "I_Net.h" are used by everywhere
>
> # after
> /include/iocore/net/Net.h
> /iocore/net/P_Net.h
>
> - include search path : ${topdir)/include
> - #include "P_Net.h" MUST be used only in the iocore/net submodule
> - other submodules MUST use #include "iocore/net/Net.h"
>
> - Masaori
>
>
> On Mon, May 13, 2019 at 11:39 PM Leif Hedstrom <zw...@apache.org> wrote:
>
>>
>>
>>> On May 13, 2019, at 8:33 AM, Walt Karas <wk...@verizonmedia.com.INVALID>
>> wrote:
>>>
>>> How about an approach using recursively nested modules?
>>> - Exported headers for a module are in the module directory.
>>> - Private headers and implementation (.cc) files are in a subdirectory
>>> named "private".
>>> - The submodules of a module are subdirectories of the module directory.
>>> - Module source files include their own exported headers with #include
>>> "../name.h"
>>> - Source files include exported headers of other modules with #include
>>> "../../module/name.h", #include "../../../module/name.h", etc. That is
>> to
>>> say, a headers name, preceded by a module name, preceded by two or more
>>> parent directory links (..). So that source files only include the
>> header
>>> files of modules that directly or indirectly contain them.
>>
>>
>> Can you please make that a little bit more complicated please?
>>
>> I’m pretty -1 on having files with the same filenames in different
>> location. I’m sure that will just break all sort of shit, including my tiny
>> brain.
>>
>> I’m leaning more towards Chao's proposal of cleaning up the actual mess.
>> If we want to rename the I_ and P_ files, that’s fine too. We moved some
>> stuff to a generic include directory, such that we can get away with just
>> one single -I${topdir)/include in the compiles, and then use #include
>> “some_major_module/P_Stuff.h”.
>>
>> Ciao,
>>
>> — leif
>>
>>>
>>> On Mon, May 13, 2019 at 1:20 AM Chao Xu <ok...@apache.org> wrote:
>>>
>>>> Hi Masaori,
>>>>
>>>> The functionality does not change as the file name changes：
>>>>
>>>> - The P_ files should contain any types and definitions that are
>>>> private to the subsystem,
>>>> - The public interface should be contained in a I_ prefixed header.
>>>>
>>>> Confusing private and public definitions will cause the code to have
>>>> circular dependencies.
>>>>
>>>> In order to solve the issue that the P_ files are included from out
>>>> side of subsystem, we have 2 choice:
>>>>
>>>> 1. Pulls related types and definitions from P_ files into I_ files (be
>>>> careful to do it).
>>>> 2. Do not include that P_ files (figure out why the P_ files is needed).
>>>>
>>>> If you just don't like the I_ and P_ prefix, you can rename the
>>>> filename as you want or put them into different directory, for
>>>> example:
>>>>
>>>> - Puts all those I_ prefix header files into iocore/api/ and keeps all
>>>> P_ prefix header files within subsystem directory.
>>>> - Compile with `-I iocore/api`
>>>>
>>>> Thanks.
>>>>
>>>> - Oknet Xu
>>>>
>>>> Masaori Koshiba <ma...@apache.org> 于2019年5月13日周一 上午9:57写道：
>>>>>
>>>>> We have a naming convention for header files, P_ or I_ prefix. Details
>>>> are
>>>>> described in below.
>>>>>
>>>>>> # Header files
>>>>>> In most subsystems, header files are named with a P_ or I_ prefix. P_
>>>>> files should contain
>>>>>> any types and definitions that are private to the subsystem, while the
>>>>> public interface
>>>>>> should be contained in a I_-prefixed header.
>>>>>
>>>>>
>>>>
>> https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
>>>>>
>>>>> But this looks obsoleted 1). many subsystem don't follow this rule, 2).
>>>>> even if this rule is
>>>>> followed, P_ files (subsystem private header files) are included from
>> out
>>>>> side of subsystem.
>>>>> (e.g. P_Net.h, P_EventSystem.h )
>>>>>
>>>>> The consensus at last summit was we should remove this rule.
>>>>>
>>>>> If there’re any real use case of subsystem private header files, we can
>>>>> move them a directory
>>>>> under the subsystem and include them internally.
>>>>>
>>>>> Any thoughts?
>>>>>
>>>>> Thanks,
>>>>> Masaori
>>>>
>>>>
>>>>
>>>> --
>>>> - Oknet Xu
>>>>
>>
>>
Re: [PROPOSAL] Remove P_ or I_ naming convention for header files
Posted by Masaori Koshiba <ma...@apache.org>.
> I’m pretty -1 on having files with the same filenames in different
location. I’m sure that will just break all sort of shit, including my tiny
brain.
I strongly agree with this.
> I’m leaning more towards Chao's proposal of cleaning up the actual mess.
If we want to rename the I_ and P_ files, that’s fine too.
We should figure out why the P_ files are needed. It looks like we don't
need them in many cases.
> We moved some stuff to a generic include directory, such that we can get
away with just one single -I${topdir)/include in the compiles, and then use
#include “some_major_module/P_Stuff.h”.
Looks reasonable. I think I_Stuff.h or Stuff.h instead P_Stuff.h.
In total, using I_/P_Net.h for example, if we really need private header
file by some reason, the change would be like this?
# before
/iocore/net/I_Net.h
/iocore/net/P_Net.h
- include search path : ${topdir)/iocore/net
- #include "P_Net.h" and #include "I_Net.h" are used by everywhere
# after
/include/iocore/net/Net.h
/iocore/net/P_Net.h
- include search path : ${topdir)/include
- #include "P_Net.h" MUST be used only in the iocore/net submodule
- other submodules MUST use #include "iocore/net/Net.h"
- Masaori
On Mon, May 13, 2019 at 11:39 PM Leif Hedstrom <zw...@apache.org> wrote:
>
>
> > On May 13, 2019, at 8:33 AM, Walt Karas <wk...@verizonmedia.com.INVALID>
> wrote:
> >
> > How about an approach using recursively nested modules?
> > - Exported headers for a module are in the module directory.
> > - Private headers and implementation (.cc) files are in a subdirectory
> > named "private".
> > - The submodules of a module are subdirectories of the module directory.
> > - Module source files include their own exported headers with #include
> > "../name.h"
> > - Source files include exported headers of other modules with #include
> > "../../module/name.h", #include "../../../module/name.h", etc. That is
> to
> > say, a headers name, preceded by a module name, preceded by two or more
> > parent directory links (..). So that source files only include the
> header
> > files of modules that directly or indirectly contain them.
>
>
> Can you please make that a little bit more complicated please?
>
> I’m pretty -1 on having files with the same filenames in different
> location. I’m sure that will just break all sort of shit, including my tiny
> brain.
>
> I’m leaning more towards Chao's proposal of cleaning up the actual mess.
> If we want to rename the I_ and P_ files, that’s fine too. We moved some
> stuff to a generic include directory, such that we can get away with just
> one single -I${topdir)/include in the compiles, and then use #include
> “some_major_module/P_Stuff.h”.
>
> Ciao,
>
> — leif
>
> >
> > On Mon, May 13, 2019 at 1:20 AM Chao Xu <ok...@apache.org> wrote:
> >
> >> Hi Masaori,
> >>
> >> The functionality does not change as the file name changes：
> >>
> >> - The P_ files should contain any types and definitions that are
> >> private to the subsystem,
> >> - The public interface should be contained in a I_ prefixed header.
> >>
> >> Confusing private and public definitions will cause the code to have
> >> circular dependencies.
> >>
> >> In order to solve the issue that the P_ files are included from out
> >> side of subsystem, we have 2 choice:
> >>
> >> 1. Pulls related types and definitions from P_ files into I_ files (be
> >> careful to do it).
> >> 2. Do not include that P_ files (figure out why the P_ files is needed).
> >>
> >> If you just don't like the I_ and P_ prefix, you can rename the
> >> filename as you want or put them into different directory, for
> >> example:
> >>
> >> - Puts all those I_ prefix header files into iocore/api/ and keeps all
> >> P_ prefix header files within subsystem directory.
> >> - Compile with `-I iocore/api`
> >>
> >> Thanks.
> >>
> >> - Oknet Xu
> >>
> >> Masaori Koshiba <ma...@apache.org> 于2019年5月13日周一 上午9:57写道：
> >>>
> >>> We have a naming convention for header files, P_ or I_ prefix. Details
> >> are
> >>> described in below.
> >>>
> >>>> # Header files
> >>>> In most subsystems, header files are named with a P_ or I_ prefix. P_
> >>> files should contain
> >>>> any types and definitions that are private to the subsystem, while the
> >>> public interface
> >>>> should be contained in a I_-prefixed header.
> >>>
> >>>
> >>
> https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
> >>>
> >>> But this looks obsoleted 1). many subsystem don't follow this rule, 2).
> >>> even if this rule is
> >>> followed, P_ files (subsystem private header files) are included from
> out
> >>> side of subsystem.
> >>> (e.g. P_Net.h, P_EventSystem.h )
> >>>
> >>> The consensus at last summit was we should remove this rule.
> >>>
> >>> If there’re any real use case of subsystem private header files, we can
> >>> move them a directory
> >>> under the subsystem and include them internally.
> >>>
> >>> Any thoughts?
> >>>
> >>> Thanks,
> >>> Masaori
> >>
> >>
> >>
> >> --
> >> - Oknet Xu
> >>
>
>
Re: [PROPOSAL] Remove P_ or I_ naming convention for header files
Posted by Leif Hedstrom <zw...@apache.org>.
> On May 13, 2019, at 8:33 AM, Walt Karas <wk...@verizonmedia.com.INVALID> wrote:
>
> How about an approach using recursively nested modules?
> - Exported headers for a module are in the module directory.
> - Private headers and implementation (.cc) files are in a subdirectory
> named "private".
> - The submodules of a module are subdirectories of the module directory.
> - Module source files include their own exported headers with #include
> "../name.h"
> - Source files include exported headers of other modules with #include
> "../../module/name.h", #include "../../../module/name.h", etc. That is to
> say, a headers name, preceded by a module name, preceded by two or more
> parent directory links (..). So that source files only include the header
> files of modules that directly or indirectly contain them.
Can you please make that a little bit more complicated please?
I’m pretty -1 on having files with the same filenames in different location. I’m sure that will just break all sort of shit, including my tiny brain.
I’m leaning more towards Chao's proposal of cleaning up the actual mess. If we want to rename the I_ and P_ files, that’s fine too. We moved some stuff to a generic include directory, such that we can get away with just one single -I${topdir)/include in the compiles, and then use #include “some_major_module/P_Stuff.h”.
Ciao,
— leif
>
> On Mon, May 13, 2019 at 1:20 AM Chao Xu <ok...@apache.org> wrote:
>
>> Hi Masaori,
>>
>> The functionality does not change as the file name changes：
>>
>> - The P_ files should contain any types and definitions that are
>> private to the subsystem,
>> - The public interface should be contained in a I_ prefixed header.
>>
>> Confusing private and public definitions will cause the code to have
>> circular dependencies.
>>
>> In order to solve the issue that the P_ files are included from out
>> side of subsystem, we have 2 choice:
>>
>> 1. Pulls related types and definitions from P_ files into I_ files (be
>> careful to do it).
>> 2. Do not include that P_ files (figure out why the P_ files is needed).
>>
>> If you just don't like the I_ and P_ prefix, you can rename the
>> filename as you want or put them into different directory, for
>> example:
>>
>> - Puts all those I_ prefix header files into iocore/api/ and keeps all
>> P_ prefix header files within subsystem directory.
>> - Compile with `-I iocore/api`
>>
>> Thanks.
>>
>> - Oknet Xu
>>
>> Masaori Koshiba <ma...@apache.org> 于2019年5月13日周一 上午9:57写道：
>>>
>>> We have a naming convention for header files, P_ or I_ prefix. Details
>> are
>>> described in below.
>>>
>>>> # Header files
>>>> In most subsystems, header files are named with a P_ or I_ prefix. P_
>>> files should contain
>>>> any types and definitions that are private to the subsystem, while the
>>> public interface
>>>> should be contained in a I_-prefixed header.
>>>
>>>
>> https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
>>>
>>> But this looks obsoleted 1). many subsystem don't follow this rule, 2).
>>> even if this rule is
>>> followed, P_ files (subsystem private header files) are included from out
>>> side of subsystem.
>>> (e.g. P_Net.h, P_EventSystem.h )
>>>
>>> The consensus at last summit was we should remove this rule.
>>>
>>> If there’re any real use case of subsystem private header files, we can
>>> move them a directory
>>> under the subsystem and include them internally.
>>>
>>> Any thoughts?
>>>
>>> Thanks,
>>> Masaori
>>
>>
>>
>> --
>> - Oknet Xu
>>
Re: [PROPOSAL] Remove P_ or I_ naming convention for header files
Posted by Walt Karas <wk...@verizonmedia.com.INVALID>.
How about an approach using recursively nested modules?
- Exported headers for a module are in the module directory.
- Private headers and implementation (.cc) files are in a subdirectory
named "private".
- The submodules of a module are subdirectories of the module directory.
- Module source files include their own exported headers with #include
"../name.h"
- Source files include exported headers of other modules with #include
"../../module/name.h", #include "../../../module/name.h", etc. That is to
say, a headers name, preceded by a module name, preceded by two or more
parent directory links (..). So that source files only include the header
files of modules that directly or indirectly contain them.
On Mon, May 13, 2019 at 1:20 AM Chao Xu <ok...@apache.org> wrote:
> Hi Masaori,
>
> The functionality does not change as the file name changes：
>
> - The P_ files should contain any types and definitions that are
> private to the subsystem,
> - The public interface should be contained in a I_ prefixed header.
>
> Confusing private and public definitions will cause the code to have
> circular dependencies.
>
> In order to solve the issue that the P_ files are included from out
> side of subsystem, we have 2 choice:
>
> 1. Pulls related types and definitions from P_ files into I_ files (be
> careful to do it).
> 2. Do not include that P_ files (figure out why the P_ files is needed).
>
> If you just don't like the I_ and P_ prefix, you can rename the
> filename as you want or put them into different directory, for
> example:
>
> - Puts all those I_ prefix header files into iocore/api/ and keeps all
> P_ prefix header files within subsystem directory.
> - Compile with `-I iocore/api`
>
> Thanks.
>
> - Oknet Xu
>
> Masaori Koshiba <ma...@apache.org> 于2019年5月13日周一 上午9:57写道：
> >
> > We have a naming convention for header files, P_ or I_ prefix. Details
> are
> > described in below.
> >
> > > # Header files
> > > In most subsystems, header files are named with a P_ or I_ prefix. P_
> > files should contain
> > > any types and definitions that are private to the subsystem, while the
> > public interface
> > > should be contained in a I_-prefixed header.
> >
> >
> https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
> >
> > But this looks obsoleted 1). many subsystem don't follow this rule, 2).
> > even if this rule is
> > followed, P_ files (subsystem private header files) are included from out
> > side of subsystem.
> > (e.g. P_Net.h, P_EventSystem.h )
> >
> > The consensus at last summit was we should remove this rule.
> >
> > If there’re any real use case of subsystem private header files, we can
> > move them a directory
> > under the subsystem and include them internally.
> >
> > Any thoughts?
> >
> > Thanks,
> > Masaori
>
>
>
> --
> - Oknet Xu
>
Re: [PROPOSAL] Remove P_ or I_ naming convention for header files
Posted by Chao Xu <ok...@apache.org>.
Hi Masaori,
The functionality does not change as the file name changes：
- The P_ files should contain any types and definitions that are
private to the subsystem,
- The public interface should be contained in a I_ prefixed header.
Confusing private and public definitions will cause the code to have
circular dependencies.
In order to solve the issue that the P_ files are included from out
side of subsystem, we have 2 choice:
1. Pulls related types and definitions from P_ files into I_ files (be
careful to do it).
2. Do not include that P_ files (figure out why the P_ files is needed).
If you just don't like the I_ and P_ prefix, you can rename the
filename as you want or put them into different directory, for
example:
- Puts all those I_ prefix header files into iocore/api/ and keeps all
P_ prefix header files within subsystem directory.
- Compile with `-I iocore/api`
Thanks.
- Oknet Xu
Masaori Koshiba <ma...@apache.org> 于2019年5月13日周一 上午9:57写道：
>
> We have a naming convention for header files, P_ or I_ prefix. Details are
> described in below.
>
> > # Header files
> > In most subsystems, header files are named with a P_ or I_ prefix. P_
> files should contain
> > any types and definitions that are private to the subsystem, while the
> public interface
> > should be contained in a I_-prefixed header.
>
> https://cwiki.apache.org/confluence/display/TS/Coding+Style#CodingStyle-Headerfiles
>
> But this looks obsoleted 1). many subsystem don't follow this rule, 2).
> even if this rule is
> followed, P_ files (subsystem private header files) are included from out
> side of subsystem.
> (e.g. P_Net.h, P_EventSystem.h )
>
> The consensus at last summit was we should remove this rule.
>
> If there’re any real use case of subsystem private header files, we can
> move them a directory
> under the subsystem and include them internally.
>
> Any thoughts?
>
> Thanks,
> Masaori
--
- Oknet Xu