Create an initial coding standard and add to wiki

[goanpeca]

No description provided.

[bemcdonnell]

We could always adopt an existing code standard for all new contributions. Then we could work backwards to update things.

[bemcdonnell]

@samhatchett, any suggestions?

[kakila]

In a multi-languaje project you will probably need several standards. In GNU Octave, for c++ we use http://wiki.octave.org/C%2B%2B_style_guide

[samhatchett]

the epanet project is talking about just using clang-format for auto formatting to make this a non-issue. apparently it can also be integrated with git hooks to make sure everything is formatted before committing.

then arguments just become about "readability" when selecting the clang-format template to use and the prevalence of comments and doxy.

[goanpeca]

Agreed with @samhatchett, have you started using it already?

[samhatchett]

I use a clang-format extension in my IDE - have not integrated with git hooks yet, and we've not decided on a format template either 😉 - would love to hear others' experience.

[goanpeca]

would love to hear others' experience. none :-p, but I use yapf (which is essentially the same idea) for Python code with the CI. So if the code is formatted we fail checks, if the code was already ok, there would not be any format at all.

We already use this on pyswmm

[kakila]

Not having an explicit code style is an open door to reduce the openness of your code. You should have a human applicable coding standard, and then automated with tools you like. Where is the definition of the clang-format? If somebody has just a text editor (plin text, no IDE, no auto format), will they be able to comply with your standard?

[goanpeca]

@kakila sometimes an explicit style cannot be emulated by an automatic tool, so its about tradeoffs, maybe the automatic formatter will not make the code 100% as what "some human" would like, but since it is performed automatically, there is no time wasted in enforcing or discussing in pull requests.

The tools have many "levers" so one can adapt settings for different things if you want to know more you ca read https://clang.llvm.org/docs/ClangFormatStyleOptions.html

If somebody has just a text editor (plain text, no IDE, no auto format), will they be able to comply with your standard?

I guess but this will vary a lot depending on the specific ide. A more actionable approach is to have a script that runs the formatter based on a configuration file (that will live in the repo), this script can then be attached to a git hook so before a commit is made, the script is run to enforce the style.

On top of this "local computer" layer we also implement the checks in the CI Infrastructure, so if by any reason someone pushes a PR that does not comply (because the auto formatter was not run previous to the commi/push) then the CI will detect this, fail accordingly and inform the user what part of the code has the "wrong" format.

[kakila]

Take my warning, the more automated and CS you go, the more difficult for your regular user to contribute to your package. This way (due to a formatting issue) you will be making the wall so high that you will not take advantage of the user community. Every time a user (they probably will label themselves as "I am not a programmer") wants to share with your community some algorithms they develo, they will be put off by the complexity of the contribution process. At the end the core developers will have to take care of actually re-coding user contributions that are valuable, putting your manpower resources in check. Unless you have a budget to keep your programmers working, you will bring yourself into a slow dying spiral. Volunteer based projects should strike a balance between contribution process complexity ("profesional", some might call it) and source code quality. The limiting factor on these projects is manpower, keep your requirements at bay. Keep your sources as close as possible to your users, without compromising too much.

my two cents.

[samhatchett]

@kakila you have some very good points. too many dev requirements spoils the openness. If I make a useful contribution, should I have to understand code formatters? or can't I just make the contribution and someone who knows about that stuff (and cares) can re-format my code when it's convenient?

In a sense, this is the same philosophical stance that leads one to adopt autoformatting in the first place - to emphasize the logic and abstractions over the presentation. 🤔

[goanpeca]

In a sense, this is the same philosophical stance that leads one to adopt autoformatting in the first place - to emphasize the logic and abstractions over the presentation. 🤔

Yep... and concentrate on things that really matter: what the code does... and not how the code looks

[goanpeca]

@kakila there is a reason why projects have a set of contributing guidelines.... a CONTRIBUTING.md on github that should list all the steps need to get the user going.

User need to know git and github and branches to contribute, that is the first "block" but still they need to learn that, now you add on top of that running a script that we will provide. How is that more difficult than already learning git and github?

All this actually will make life way easier on contributors and developers and maintainers alike, that is the whole point, is not about making development professional, is about making the best of limited resources via automation. Discussing code format and enforcing it via comments on pull requests is a very very bad use of developer maintainer and contributor time.