ITKv4 StyleChangeProposal

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. 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. 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. 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.

Experience

The attached uncrustify (http://uncrustify.sourceforge.net/) configuration file closely matches the KWStyle (except for the inconsistent function brace indentation). http://www.itk.org/Wiki/images/6/62/Uncrustify_itk.txt File:Uncrustify itk.txt

#!/bin/bash
## Author Hans J. Johnson
## The goal of this script is to develop a consistent system of auto-formating
## and format testing such that if uncrustify is run, then the code will pass
## the KWStyle format checker.

## http://www.itk.org/Wiki/ITKv4_StyleChangeProposal

#### Loop to auto check uncrustify.
ITK_DIR=$1  ## The base directory of ITK
LOCAL_DIR=$(dirname $0)

RESULT_FILE=test.logger

KWSTYLEBIN=~/src/KWStyle-build/bin/KWStyle
UNCRUSTIFYBIN=~/local/bin/uncrustify

OWF=${LOCAL_DIR}/KWStyle/ITKOverwrite.txt
RULES=${LOCAL_DIR}/KWStyle/ITK.cvs.kws.xml

rm -rf ${RESULT_FILE}
cd ${ITK_DIR}/Code
for i in $(find . -name "*.cxx" |fgrep -v orig; find . -name "*.h"|fgrep -v orig; find . -name "*.txx"|fgrep -v orig); do
#for i in $(find . -name itkHexahedronCellTopology.cxx); do
  ORIG=${i}.orig.cxx
  if [ ! -f ${ORIG} ]; then
    cp ${i} ${ORIG}
  fi
  ${KWSTYLEBIN} -v -o ${OWF} -xml ${RULES} ${ORIG} >> /dev/null 2>&1
  ORIG_STATUS=$?
  ${UNCRUSTIFYBIN} -c ${LOCAL_DIR}/uncrustify_itk.txt -l CPP -f ${ORIG} -o ${i}.temp >> /dev/null 2>&1
  diff  ${ORIG}  ${i}.temp > /dev/null 2>&1
  if [ $? -eq 0 ]; then
    rm ${i}.temp
  else
    mv ${i}.temp ${i}
  fi
  ${KWSTYLEBIN} -v  -o ${OWF} -xml ${RULES} ${i} |tee ${i}.kwerrors
  CLEANED_STATUS=$?
  if [ ${CLEANED_STATUS} -ne 0 ]; then
    echo "${i}: ${ORIG_STATUS} --> ${CLEANED_STATUS}" |tee -a ${RESULT_FILE}
  fi
  echo "========"
done |tee ${LOCAL_DIR}/ERRORS.logger


echo "PLEASE COMPILE AND TEST ITK"

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