[Insight-developers] Proposal to change file naming conventions

Wed Apr 20 08:47:09 EDT 2011

> 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

>
>
> On 4/20/11 1:51 AM, "Tom Vercauteren" <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>
>>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> 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
>>>>
>>>> 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
>>>
>>> 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
>
> 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