Code cleanup checklist

[jhamman]

Now that 4.2 has been released, we can move forward on cleaning up the source code. I spent a bit of time reading back through our discussion in #7, #48, and #134 and will try and provide an outline of what we need to do in order to close those issues. One common thread that I think we want to stick to is to only keep documentation that is relevant and needed, extra stuff just leads to confusion down the road.

Code Cleanup:

• Remove unused variables (Remove unused variables #134)
• Remove relic "commented out" code (e.g. this example)
• Remove hard coded literals (e.g. 905ef48)
• Fix include statements (fix include syntax for header files #163)

Code Formatting (#48):

• Run Uncrustify of all source files in repository. @bartnijssen has already put together an uncrustify options template.

• Implement a consistent file header format. In my opinion we should adopt a common format that would also play nice with code documentation tools like doxygen. This would include the following pieces:

  • filename
  • original author(s)
  • description
  • license boilerplate

  _Example header format:_

  /*
  * \section DESCRIPTION
  *
  * A short description 
  *
  * \section LICENSE
  *
  * The Variable Infiltration Capacity (VIC) macroscale hydrological model
  * Copyright (C) 2014  The Land Surface Hydrology Group, Department of Civil
  * and Environmental Engineering, University of Washington.
  *
  * The VIC model is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
  * as published by the Free Software Foundation; either version 2
  * of the License, or (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License along with
  * this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */

• Implement a consistent function header format (done in source files). This would include the following pieces:

  • description
  • citation (optional)
  • input parameters (optional)
  • return value

  _Example function header format:_

  /*
  * \brief        description of function
  */
  int my_fun(double name1, double name2, int name3) {
  ...
  }

[jhamman]

closed via #169.