Code linting and Formatting

[bemcdonnell]

Dare I ask, @michaeltryby and @cbuahin what are your opinions of adding linters to the C/CPP/H/HPP files? As I continue to merge in the updates from EPA into PySWMM's SWMM codebase, I find that spaces appear and then disappear. It would be cool if we could go through the merge pain one time with a freshly linted and code format strategy.

We had this wild idea years ago at the former "OWA-SWMM", now PySWMM(SWMM), project. However, we decided against it since the USEPA upstream wasn't not heading in the direction. I am for sure grateful that the codebase is working toward dropping the line comments specifying the codebase version introducing the changes.

Here is the PR: pyswmm#88

[LRossman]

I just used cpplint to check a file I have been refactoring. It was really useful in identifying spaces at the end of lines. However because it uses the Google styling format you have to run it with -whitespace/braces,-readability/braces filters so it doesn't report SWMM's placing of opening curly braces on a new line as an error. There is also guidance on adding it to GitHub workflow actions to run it each time new code is pushed into a repo.

While using cpplint I thought it might be useful to have a SWMM 5 Style Guide for this project. A draft version of such a guide, based on the style currently used throughout SWMM, is attached.

Draft SWMM 5 Style Guide.md

[cbuahin]

A lot of good ideas to consider with all of the internal planning that is ongoing.

[cbuahin]

I need to add that we are strongly considering adopting doxygen to document the code and for doing the documentation for SWMM in general. The style we are adopting will therefore have to conform to it. An example can be found here.

[dickinsonre]

Is one of the EPANET versions using doxygen for documentation? Or was it just read the docs https://epanet22.readthedocs.io/en/latest/6_objects.html

[LRossman]

The Read the Docs document contains an on-line version of the EPANET User's Manual that describes how to run EPANET through its GUI (like the EPA SWMM User's Guide does). The OWA-EPANET project, which like this SWMM project only includes the EPANET engine, used Doxygen to document its API functions (through specially formatted comments in the source code) coupled with some additional files that describe how to use the API. The final product can be found here. Doxygen is typically used only to describe API libraries and the classes and functions they publish, not to document the complete source code.

[cbuahin]

While not typically used, Doxygen provides capabilities to add documentation beyond just the descriptions of api and classes. Markdown files can be added and configured to produce latex, pdfs, docbooks, and other formats. It comes with the hyperlinks and allows us to incorporate complex math expressions in TeX and LaTeX style syntax. It will provide a good opportunity to kill two birds with one stone. Anyway, nothing is set in stone. We are only exploring.

[bemcdonnell]

@cbuahin, equations like this, right?

Stone + two birds....

🪨+ 🦅+ 🦅 == 💥 💥 == 🪨 🍗 🍗

[michaeltryby]

@cbuahin Shouldn't be a problem to accommodate Doxygen format in the style guide.