[Insight-developers] Proposal to change file naming conventions

Cory Quammen cquammen at cs.unc.edu
Wed Apr 20 09:33:40 EDT 2011 

Yes, you should be able to add "*-impl.h" to the EXCLUDE_PATTERNS option.

Cory

On Wed, Apr 20, 2011 at 9:07 AM, David Cole <david.cole at kitware.com> wrote:
> We could easily exclude "-impl.h" files from doxygen, couldn't we?
>
>
> On Wed, Apr 20, 2011 at 8:58 AM, Gelas, Arnaud Joel Florent
> <Arnaud_Gelas at hms.harvard.edu> wrote:
>>
>> I also like the "-impl.h", however I have one concern doxygen scan all *.h
>> files...
>> Such a change will increase the time to generate the doxygen
>> documentation, so I'd prefer a different extension.
>>
>> Arnaud
>>
>>
>>
>> ________________________________________
>> From: insight-developers-bounces at itk.org
>> [insight-developers-bounces at itk.org] On Behalf Of David Cole
>> [david.cole at kitware.com]
>> Sent: Wednesday, April 20, 2011 8:50 AM
>> To: Cory Quammen
>> Cc: Tom Vercauteren; Johnson,   Hans J; ITK
>> Subject: Re: [Insight-developers] Proposal to change file naming
>> conventions
>>
>> On Wed, Apr 20, 2011 at 8:47 AM, Cory Quammen
>> <cquammen at cs.unc.edu<mailto:cquammen at cs.unc.edu>> wrote:
>> > 1)  Personally I like the google c++ style approach a lot (ie. -inl.h)
>> > because it more clearly describes the intent of what should be in the
>> > file
>> >
>> > (http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#The_-inl.h_
>> > Files).  I proposed the ".hpp" option mainly as a starting point for
>> > discussion purposes.
>>
>> My two cents: I think the "-impl.h" suffix offers the clearest
>> description of what the file contains.
>>
>> Cory
>>
>>
>> I also think "-impl.h" more clearly describes things... It's the
>> implementation of something, it's not necessarily all "inline"...
>>
>> I like this idea.
>>
>>
>> David C.
>>
>>
>>
>> >
>> >
>> > On 4/20/11 1:51 AM, "Tom Vercauteren"
>> > <tom.vercauteren at m4x.org<mailto:tom.vercauteren at m4x.org>> wrote:
>> >
>> >>Hi Hans,
>> >>
>> >>I like the overall proposal but agree with Bill that simply changing
>> >>.txx to .hpp (or .hxx) will be confusing. Many large libraries (e.g.
>> >>boost) use .hpp for "all-in-one" template headers.
>> >>
>> >>I like, the alternative proposed in the google c++ style guide you
>> >>sent use: "-inl.h". Anything similar to this would also be fine for
>> >>me, e.g. "-inl.hpp",  "-impl.h",  "-impl.hpp", etc.
>> >>
>> >>The backward compatibility glitches seem ok to handle on my side given
>> >>the benefits for newcomers. If other people feel differently, we may
>> >>also create .txx files that simply wrap (i.e. include) the new files
>> >>implementation files and move these .txx in the deprecated module.
>> >>
>> >>Also, while we are at improving support for common development tools,
>> >>it would be add a list of all "headers" to the CMakeLists.txt. This is
>> >>required at least in visual studio, qtcreator and maybe also xcode to
>> >>make the template files appear in the IDE. See, e.g.
>> >>
>>
>> >> >>http://stackoverflow.com/questions/1167154/listing-header-files-in-visual-
>> >>studio-c-project-generated-by-cmake
>> >>
>> >>Hence, what we do in our projects goes along these lines:
>> >>
>> >>set( ITK-MyModule_SRC
>> >>  itkFile0.cxx
>> >>  )
>> >>
>> >>set( ITK-MyModule_HDR_ONLY
>> >>  itkFile1.h
>> >>  itkFile1-impl.h
>> >>  itkFile2.h
>> >>  itkFile2-impl.h
>> >>  )
>> >>
>> >>source_group(
>> >>  "Template and Header Only Files" FILES ${ITK-MyModule_HDR_ONLY}
>> >>)
>> >>
>> >>add_library(ITK-MyModule ${ITK-MyModule_SRC} ${ITK-MyModule_HDR_ONLY})
>> >>
>> >>
>> >>My two cents,
>> >>Tom
>> >>
>> >>On Wed, Apr 20, 2011 at 05:42, Bill Lorensen
>> >> <bill.lorensen at gmail.com<mailto:bill.lorensen at gmail.com>>
>> >>wrote:
>> >>> Hans,
>> >>>
>> >>> This is an interesting proposal. And I think it is backwards
>> >>> compatible.
>> >>>
>> >>> However, .hpp is a bit confusing since we already use .h. I believe
>> >>> that projects usually choose one or the other, but not both. Users may
>> >>> get confused as to which to include, especially if their projects are
>> >>> using .hpp for "include" files. Do you have an example of a project
>> >>> that uses both .h and .hpp files?
>> >>>
>> >>> Perhaps we should look harder for a better convention.
>> >>> For example, eigen just has .h files. The equivalent of our .txx is
>> >>> kept in the .h file.
>> >>> Also wtl uses the same convention. Also tclap.
>> >>>
>> >>> Bill
>> >>>
>> >>> On Tue, Apr 19, 2011 at 10:13 PM, Johnson, Hans J
>> >>> <hans-johnson at uiowa.edu<mailto:hans-johnson at uiowa.edu>> wrote:
>> >>>> Hello All,
>> >>>> I have a proposal for easing development of ITK for many development
>> >>>> environments.
>> >>>> A reference implementation is given:
>> >>>> http://review.source.kitware.com/#change,1450
>> >>>>
>> >>>> PREMISE:
>> >>>>
>> >>>> The  use of the .txx file extension for indicating the file that is
>> >>>> to
>> >>>>hold
>> >>>> the implementation of a template class is only adopted by the ITK
>> >>>>community
>> >>>> and VNL communities (and has  slightly ³infected² a few other small
>> >>>> components of other projects).
>> >>>>
>> >>>> Increasingly tools are being created to help the programmer better
>> >>>> understand and analyze, and provide hints to proper coding options
>> >>>> dynamically in the development environment (color coding,
>> >>>>auto-completion).
>> >>>> The obscure .txx file requires special configuration of each
>> >>>>development
>> >>>> environment tool to indicate that it is really a c++ header.  For new
>> >>>> developers this is often a difficult and frustrating task.  This is
>> >>>> confirmed by the large amount of documentation for just a few of the
>> >>>>common
>> >>>> editors.  Tools that recognize and respect the .hpp extension (or
>> >>>> ³-ipl.h²):  uncrustify, vim, emacs, VisualStudios, clang, SlickEdit,
>> >>>>kwrite,
>> >>>> etc....)  None of these tools recognize the .txx extension without
>> >>>> end
>> >>>>user
>> >>>> customizations.
>> >>>>
>> >>>>
>> >>>>
>> >>>> CONS:
>> >>>>
>> >>>> --Many files will be changed, and it will not be backwards compatible
>> >>>>for
>> >>>> those who accidently included the ³.txx² files in their projects.
>> >>>>  The
>> >>>>.txx
>> >>>> files should not be included in external packages
>> >>>>
>> >>>>
>> >>>>
>> >>>> BENEFITS:
>> >>>>
>> >>>> n  Implementation files are properly mapped to C++ language type by
>> >>>>default
>> >>>> for improved development environment experience.
>> >>>>
>> >>>> n
>> >>>>
>> >>>>
>> >>>>
>> >>>> CONSIDERATIONS:
>> >>>>
>> >>>> There is no obvious single correct solution, but in general a common
>> >>>>theme
>> >>>> from other guides is that the final extension should be ³.hpp² or
>> >>>>  some
>> >>>> suffix that ends with ³.h².  The extension should be all lower case
>> >>>>letters
>> >>>> (to avoid problems on case insensitive file sysetms).
>> >>>>
>> >>>> http://www.parashift.com/c++-faq-lite/coding-standards.html
>> >>>>
>> >>>>
>> >>>>
>> >>>> http://www.cplusplus.com/forum/beginner/5882/
>> >>>>
>> >>>>
>> >>>>
>> >>>> ³Back in the old CFront days, there was a .C and .H convention for
>> >>>> C++
>> >>>> source and header files to avoid conflict with .c and .h for C.
>> >>>>However,
>> >>>> MS-DOS used a case-insensitive file system and soused .cpp and .hpp
>> >>>>instead.
>> >>>> Visual Studio's parser still recongnises .hpp and .inl as C++ files,
>> >>>>so it's
>> >>>> not a completely forgotten form.²
>> >>>>
>> >>>>
>> >>>>
>> >>>>
>>
>> >>>> >>>>http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#The_-inl.
>> >>>>h_Files
>> >>>>
>> >>>>
>> >>>>
>> >>>> PROPOSAL:
>> >>>>
>> >>>> In ITKv4 (and outside of the ThirdParty directory) change all
>> >>>>implementation
>> >>>> files that currently have a ³.txx² extension to have a ³.hpp²
>> >>>>extension.
>> >>>>
>> >>>>
>> >>>>
>> >>>> ________________________________
>> >>>> Notice: This UI Health Care e-mail (including attachments) is covered
>> >>>>by the
>> >>>> Electronic Communications Privacy Act, 18 U.S.C. 2510-2521, is
>> >>>>confidential
>> >>>> and may be legally privileged.  If you are not the intended
>> >>>> recipient,
>> >>>>you
>> >>>> are hereby notified that any retention, dissemination, distribution,
>> >>>> or
>> >>>> copying of this communication is strictly prohibited.  Please reply
>> >>>> to
>> >>>>the
>> >>>> sender that you have received the message in error, then delete it.
>> >>>>Thank
>> >>>> you.
>> >>>> ________________________________
>> >>>> _______________________________________________
>> >>>> Powered by www.kitware.com<http://www.kitware.com>
>> >>>>
>> >>>> Visit other Kitware open-source projects at
>> >>>> http://www.kitware.com/opensource/opensource.html
>> >>>>
>> >>>> Kitware offers ITK Training Courses, for more information visit:
>> >>>> http://kitware.com/products/protraining.html
>> >>>>
>> >>>> Please keep messages on-topic and check the ITK FAQ at:
>> >>>> http://www.itk.org/Wiki/ITK_FAQ
>> >>>>
>> >>>> Follow this link to subscribe/unsubscribe:
>> >>>> http://www.itk.org/mailman/listinfo/insight-developers
>> >>>>
>> >>>>
>> >>> _______________________________________________
>> >>> Powered by www.kitware.com<http://www.kitware.com>
>> >>>
>> >>> Visit other Kitware open-source projects at
>> >>> http://www.kitware.com/opensource/opensource.html
>> >>>
>> >>> Kitware offers ITK Training Courses, for more information visit:
>> >>> http://kitware.com/products/protraining.html
>> >>>
>> >>> Please keep messages on-topic and check the ITK FAQ at:
>> >>> http://www.itk.org/Wiki/ITK_FAQ
>> >>>
>> >>> Follow this link to subscribe/unsubscribe:
>> >>> http://www.itk.org/mailman/listinfo/insight-developers
>> >>>
>> >
>> >
>> >
>> > ________________________________
>> > Notice: This UI Health Care e-mail (including attachments) is covered by
>> > the Electronic Communications Privacy Act, 18 U.S.C. 2510-2521, is
>> > confidential and may be legally privileged.  If you are not the intended
>> > recipient, you are hereby notified that any retention, dissemination,
>> > distribution, or copying of this communication is strictly prohibited.
>> >  Please reply to the sender that you have received the message in error,
>> > then delete it.  Thank you.
>> > ________________________________
>> > _______________________________________________
>> > Powered by www.kitware.com<http://www.kitware.com>
>> >
>> > Visit other Kitware open-source projects at
>> > http://www.kitware.com/opensource/opensource.html
>> >
>> > Kitware offers ITK Training Courses, for more information visit:
>> > http://kitware.com/products/protraining.html
>> >
>> > Please keep messages on-topic and check the ITK FAQ at:
>> > http://www.itk.org/Wiki/ITK_FAQ
>> >
>> > Follow this link to subscribe/unsubscribe:
>> > http://www.itk.org/mailman/listinfo/insight-developers
>> >
>>
>>
>>
>> --
>> Cory Quammen
>> Computer Integrated Systems for Microscopy and Manipulation (CISMM)
>> Department of Computer Science
>> University of North Carolina at Chapel Hill
>> http://www.cs.unc.edu/~cquammen<http://www.cs.unc.edu/%7Ecquammen>
>> _______________________________________________
>> Powered by www.kitware.com<http://www.kitware.com>
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Kitware offers ITK Training Courses, for more information visit:
>> http://kitware.com/products/protraining.html
>>
>> Please keep messages on-topic and check the ITK FAQ at:
>> http://www.itk.org/Wiki/ITK_FAQ
>>
>> Follow this link to subscribe/unsubscribe:
>> http://www.itk.org/mailman/listinfo/insight-developers
>>
>
>



-- 
Cory Quammen
Computer Integrated Systems for Microscopy and Manipulation (CISMM)
Department of Computer Science
University of North Carolina at Chapel Hill
http://www.cs.unc.edu/~cquammen

More information about the Insight-developers mailing list