ITKv4 StyleChangeProposal

From KitwarePublic
Revision as of 16:55, 5 September 2010 by Ibanez (talk | contribs) (→‎Experience)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Importance of consistent style

It is recognized that preferences in coding style varies widely from developer to developer. It is, however, important that the entire ITK toolkit have a consistent well defined style so that the entire toolkit appears to have been written by a single developer.

Guidelines for changing the style

    1. Should be similar to the existing style
    2. Changes from existing style should be driven to ease maintenance of the the consistent style
    3. (Others)

Current Status

    1. The current style document was written 7 years ago and has not been updated since then, and is a great reference document, but contains some ambiguity/inconsistencies
    2. The de-facto enforcement is that the code passes the KWStyle validation tester, and it appears that in at least one case (indentation) the KWStyle program is taking advantage of ambiguities in the style document to have different rules for indenting functions based on namespace and
    3. function declarations are nested inside namespace and class levels, and are currently KWStyle requires that the braces have a 2 space indentation
    4. function definitions are not nested inside the class level, and KWStyle requires that the braces are at column zero of the function
    5. KWStyle has been given too much authority in dictating the style rather than just checking it. We need to recognize that code that does not pass KWStyle may still be compliant with the standard, AND more importantly that making code pass KWStyle is in conflict with the guidelines.

Proposal

    1. Rules should be as simple to follow as possible, with as few conditionals as possible (i.e. all functions should have braces start at either column 0 or column 2 irregardless of if it is a declaration or a definition, or if it is nested inside a class)
    2. Rules should be compatible with automated reformatting utilities (uncrustify)
    3. Rules should be at least partially compatible with a wide range of editors (vim, emacs, VS) autoformatting capabilities (This may require more extensive style changes to make this occur)
    4. KWStyle should be updated to allow passing of the style.
    5. CMakeLists.txt key words should use the lower case variant to match documentation.
    6. CVS auto inserted KeyWords should be removed
>   Module:    $RCSfile: itkImageIOBase.h,v $
>   Date:      $Date: 2009-11-29 15:51:11 $
>   Version:   $Revision: 1.56 $


Experience

The uncrustify configuration file (below) closely matches the KWStyle (except for the inconsistent function brace indentation). 


See attached file that needs to be renamed with .sh extension

How to run uncrustify in ITK

 ${UNCRUSTIFYBIN} -c ${LOCAL_DIR}/uncrustify_itk.txt -l CPP -f ${ORIG} -o ${i}.temp

Issues

  1. In deeply nested large macros (like those in itkMacro.h), It sometimes gets confused, and adds spaces around “##” and “#” symbols that are supposed to be string replacements in the macro.
    • Hans have fixed this with a little “sed” magic in the script referenced from the wiki page.
  2. For end of line comments that begin after the 80th column, sometime multiple runs of uncrustify will create extraneous blank comment lines aligned with the previous comment lines (so that running uncrustify 100 times would result in a 100 empty comment lines aligned with the original comment.
  3. When the declaration of static const arrays or structures occurs where the definition of the variables are within #ifdefs and the initialization {} are outside the ifdefs, then uncrustify thinks that the ; at the end of the initializing {} is extraneous, and removes i

Proposed CXX File for Testing KWStyle

//                                                                              
// new way; should pass                                                         
void Function()
{
  int i;
}

class C
{
public:
  void ClassMethod()
  { // new 2; old 4                                                             
    int i;
  } // new 2; old 4                                                             
};

void FunctionWithLocalClass()
{
  class LocalClass
  { // new 2; old 4                                                             
  public:
    void LocalClassMethod()
    { // new 4; old 6                                                           
      int i;
    } // new 4; old 6                                                           
  }; // new 2; old 4                                                            
}

//                                                                              
// old way; should fail                                                         
void Function()
{
  int i;
}

class C
{
public:
  void ClassMethod()
    { // new 2; old 4                                                           
    int i;
    } // new 2; old 4                                                           
};

void FunctionWithLocalClass()
{
  class LocalClass
    { // new 2; old 4                                                           
  public:
      void LocalClassMethod()
      { // new 4; old 6                                                         
      int i;
      } // new 4; old 6                                                         
    }; // new 2; old 4                                                          
}
  • CMakeLists.txt Style

Recent versions of cmake documentation have gone to using all lower case key words. In order to make ITKv4 consistent with the printed documentation, ITKv4 should also follow this convention.

This vim macro accomplishes the task easily, and has been tested on the BRAINS source code base. 

:%s!ADD_CUSTOM_COMMAND\( *\)(!add_custom_command\2(!g
:%s!ADD_CUSTOM_TARGET\( *\)(!add_custom_target\2(!g
:%s!ADD_DEFINITIONS\( *\)(!add_definitions\2(!g
:%s!ADD_DEPENDENCIES\( *\)(!add_dependencies\2(!g
:%s!ADD_EXECUTABLE\( *\)(!add_executable\2(!g
:%s!ADD_LIBRARY\( *\)(!add_library\2(!g
:%s!ADD_SUBDIRECTORY\( *\)(!add_subdirectory\2(!g
:%s!subdirs\( *\)(!add_subdirectory\2(!g
:%s!SUBDIRS\( *\)(!add_subdirectory\2(!g
:%s!ADD_TEST\( *\)(!add_test\2(!g
:%s!AUX_SOURCE_DIRECTORY\( *\)(!aux_source_directory\2(!g
:%s!BREAK\( *\)(!break\2(!g
:%s!BUILD_COMMAND\( *\)(!build_command\2(!g
:%s!CMAKE_MINIMUM_REQUIRED\( *\)(!cmake_minimum_required\2(!g
:%s!CMAKE_POLICY\( *\)(!cmake_policy\2(!g
:%s!CONFIGURE_FILE\( *\)(!configure_file\2(!g
:%s!CREATE_TEST_SOURCELIST\( *\)(!create_test_sourcelist\2(!g
:%s!DEFINE_PROPERTY\( *\)(!define_property\2(!g
:%s!ELSE\( *\)(!else\2(!g
:%s!ELSEIF\( *\)(!elseif\2(!g
:%s!ENABLE_LANGUAGE\( *\)(!enable_language\2(!g
:%s!ENABLE_TESTING\( *\)(!enable_testing\2(!g
:%s!ENDFOREACH\( *\)(!endforeach\2(!g
:%s!ENDFUNCTION\( *\)(!endfunction\2(!g
:%s!ENDIF\( *\)(!endif\2(!g
:%s!ENDMACRO\( *\)(!endmacro\2(!g
:%s!ENDWHILE\( *\)(!endwhile\2(!g
:%s!EXECUTE_PROCESS\( *\)(!execute_process\2(!g
:%s!EXPORT\( *\)(!export\2(!g
:%s!FILE\( *\)(!file\2(!g
:%s!FIND_FILE\( *\)(!find_file\2(!g
:%s!FIND_LIBRARY\( *\)(!find_library\2(!g
:%s!FIND_PACKAGE\( *\)(!find_package\2(!g
:%s!FIND_PATH\( *\)(!find_path\2(!g
:%s!FIND_PROGRAM\( *\)(!find_program\2(!g
:%s!FLTK_WRAP_UI\( *\)(!fltk_wrap_ui\2(!g
:%s!FOREACH\( *\)(!foreach\2(!g
:%s!FUNCTION\( *\)(!function\2(!g
:%s!GET_CMAKE_PROPERTY\( *\)(!get_cmake_property\2(!g
:%s!GET_DIRECTORY_PROPERTY\( *\)(!get_directory_property\2(!g
:%s!GET_FILENAME_COMPONENT\( *\)(!get_filename_component\2(!g
:%s!GET_PROPERTY\( *\)(!get_property\2(!g
:%s!GET_SOURCE_FILE_PROPERTY\( *\)(!get_source_file_property\2(!g
:%s!GET_TARGET_PROPERTY\( *\)(!get_target_property\2(!g
:%s!GET_TEST_PROPERTY\( *\)(!get_test_property\2(!g
:%s!IF\( *\)(!if\2(!g
:%s!INCLUDE\( *\)(!include\2(!g
:%s!INCLUDE_DIRECTORIES\( *\)(!include_directories\2(!g
:%s!INCLUDE_EXTERNAL_MSPROJECT\( *\)(!include_external_msproject\2(!g
:%s!INCLUDE_REGULAR_EXPRESSION\( *\)(!include_regular_expression\2(!g
:%s!INSTALL\( *\)(!install\2(!g
:%s!LINK_DIRECTORIES\( *\)(!link_directories\2(!g
:%s!LIST\( *\)(!list\2(!g
:%s!LOAD_CACHE\( *\)(!load_cache\2(!g
:%s!LOAD_COMMAND\( *\)(!load_command\2(!g
:%s!MACRO\( *\)(!macro\2(!g
:%s!MARK_AS_ADVANCED\( *\)(!mark_as_advanced\2(!g
:%s!MATH\( *\)(!math\2(!g
:%s!MESSAGE\( *\)(!message\2(!g
:%s!OPTION\( *\)(!option\2(!g
:%s!OUTPUT_REQUIRED_FILES\( *\)(!output_required_files\2(!g
:%s!PROJECT\( *\)(!project\2(!g
:%s!QT_WRAP_CPP\( *\)(!qt_wrap_cpp\2(!g
:%s!QT_WRAP_UI\( *\)(!qt_wrap_ui\2(!g
:%s!REMOVE_DEFINITIONS\( *\)(!remove_definitions\2(!g
:%s!RETURN\( *\)(!return\2(!g
:%s!SEPARATE_ARGUMENTS\( *\)(!separate_arguments\2(!g
:%s!SET\( *\)(!set\2(!g
:%s!SET_DIRECTORY_PROPERTIES\( *\)(!set_directory_properties\2(!g
:%s!SET_PROPERTY\( *\)(!set_property\2(!g
:%s!SET_SOURCE_FILES_PROPERTIES\( *\)(!set_source_files_properties\2(!g
:%s!SET_TARGET_PROPERTIES\( *\)(!set_target_properties\2(!g
:%s!SET_TESTS_PROPERTIES\( *\)(!set_tests_properties\2(!g
:%s!SITE_NAME\( *\)(!site_name\2(!g
:%s!SOURCE_GROUP\( *\)(!source_group\2(!g
:%s!STRING\( *\)(!string\2(!g
:%s!TARGET_LINK_LIBRARIES\( *\)(!target_link_libraries\2(!g
:%s!TRY_COMPILE\( *\)(!try_compile\2(!g
:%s!TRY_RUN\( *\)(!try_run\2(!g
:%s!UNSET\( *\)(!unset\2(!g
:%s!VARIABLE_WATCH\( *\)(!variable_watch\2(!g
:%s!WHILE\( *\)(!while\2(!g
:%s!BUILD_NAME\( *\)(!build_name\2(!g
:%s!EXEC_PROGRAM\( *\)(!exec_program\2(!g
:%s!EXPORT_LIBRARY_DEPENDENCIES\( *\)(!export_library_dependencies\2(!g
:%s!INSTALL_FILES\( *\)(!install_files\2(!g
:%s!INSTALL_PROGRAMS\( *\)(!install_programs\2(!g
:%s!INSTALL_TARGETS\( *\)(!install_targets\2(!g
:%s!LINK_LIBRARIES\( *\)(!link_libraries\2(!g
:%s!MAKE_DIRECTORY\( *\)(!make_directory\2(!g
:%s!REMOVE\( *\)(!remove\2(!g
:%s!SUBDIR_DEPENDS\( *\)(!subdir_depends\2(!g
:%s!SUBDIRS\( *\)(!subdirs\2(!g
:%s!USE_MANGLED_MESA\( *\)(!use_mangled_mesa\2(!g
:%s!UTILITY_SOURCE\( *\)(!utility_source\2(!g
:%s!VARIABLE_REQUIRES\( *\)(!variable_requires\2(!g
:%s!WRITE_FILE\( *\)(!write_file\2(!g
Retrieved from "https://public.kitware.com/Wiki/index.php?title=ITKv4_StyleChangeProposal&oldid=29880"