Work-road to track simple tasks to improve the codebase

[AxelKrypton]

This issue is meant as parent issue for different tasks that are meant to improve the codebase from different points of view. The following check-list is shortly explaining each task and GitHub offer the possibility to convert each item in a new dedicated issue. @elfnerhannah I compiled the list with @RobinSattler who had taken notes of possible ideas, combining his input with my list. We can also decide together when to do what and who to assign. I will already open issues for tasks that I believe should be done soon-ish.

• Set up GitHub actions
  These are meant to check if the codebase compiles, format it (from within the actions with a commit done by the GitHub bot) and run tests. PRs should then be mergeable only if actions pass. Issue Add formatter script to sampler codebase #30 should be tackled before this.
• Rewrite CMake code to set up the project #53
• Better testing
  A unit testing framework is in place and it should be easily possible to add unit tests when working on the code e.g. about the other issues here around or adding new functionality. It would be worth adding some CMake functionality to create new tests as needed.
• Use C++ STL std::filesystem for output everywhere
  At the moment some C-style system call are used, but C++ offers since C++17 all needed tools to deal with this. While tackling this, it would be nice to add a mechanism that prevents existing output from being overwritten.
• Make a copy of config file into the output folder adding to it relevant metadata
  This is important for data reproducibility. It would be nice to ignore comments when parsing the config, such that this stored config can directly be reused.
• Consider using YAML for the config file
  Since SMASH does so and the handler uses SMASH as a library, this would be basically for free. The smash::Configuration object might probably even be used (although without validation ATM).
• Improve standard output
  The user needs to know a lot of details to understand what the program is printing to the screen. This might be simply improved making it descriptive.
• Think about a documentation strategy
  At the moment there is nothing else beyond the README file.
• Add a CONTRIBUTING.md file #46
• Apply IOSP (integration-operation segregation principle) as much as possible
  This would make the top-level of the code much more readable as entry point (basically main just calls functions).

Most of the tasks above can be used as exercise for new students to make them get familiar with the GitHub infrastructure. @yukarpenko This might be also useful in case you have new people in your group. 😊

[yukarpenko]

So, I've removed my previous messages since there may have been some misunderstanding. Here's a condensed view from my side.
I am interested in improving the code physics-wise (efficiency of generation, maybe canonical effects). Interested means that it is still below other items in my todo list for the near future. Plus, I do not have any students, especially for the tasks like those. But if you want to cooperate with physics-wise improvements, or correct possible bugs/mistakes, or, e.g. explore how much mess are viscous corrections, and how uncertain the sampling actually is, I'd be happy to get involved.
What you've mentioned are cosmetic changes, which do not (and should not) change the code. Some of them are useful to my opinion, yes. So if it makes you happy to do it, that's great, but I would like to mostly stay out of it. The only thing I would like to happen is that you separate the changes you've mentioned from any possible change to the actual algorithm, because the latter I prefer (based on history) to be always discussed.
So if you want to do some physics, we can set up a separate plan.

[AxelKrypton]

The fact you are interested in physics only was and is clear to me, although it is very narrow-minded to believe that "improving the code physics-wise" is a totally distinct thing from improving the code from the computer-programming perspective. There is not such a separation and I will never buy the argument "I have no time to write good code, I need to do science". Why? Well, let's see how it works: We focus on physics and do not care about code quality. Few weeks later we have crappy results and discover to have implemented something wrong. A bit of debugging, change here and there, done. Imagine if society worked like that: That bug might have made a plane crash, a medical device fail, a lift collapse, a self-driving car go out of control, a rollercoaster jump out of track, etc. I hope we agree nobody expects nor wants nor would tolerate that. Is it morally different in science?

What you've mentioned are cosmetic changes, which do not (and should not) change the code.

❌ Nope. That's just plain wrong. None is a cosmetic change. Those are changes which makes developer/user life much better and ensure a much more solid framework in which bugs are less and less likely to sneak in. About not changing the code, this is another sad misconception. How can you guarantee that the code was not changed? You can only if you have a complete suite of tools (people call them acceptance tests) that you can run and tell you where you stand. Those should be delivered with (or at least next to) the software.

About the lack of time and the feeling that all of this "cosmetics" slow down science, I am totally certain that this is nothing but a feeling and a false myth. «To go fast, you go well» - to cite R.C. Martin. When a project is in a clean state, everybody working with it (especially new people, which might be people coming back to the project after lots of time) does not spend a big amount of time (to get frustrated) reading the code over and over again and being unsure doing any change. Just the opposite: You enable people to be confident in making changes and work with a codebase they barely know.

---

Long story short: I will try to find time at some point to deal with some of the open issues. You can focus on physics. It is actually the same thing. We should just acknowledge that it would be nice to have more time to deal with everything differently and that, since we do not have resources, we try to find the best compromise. But this does not mean to try convince people that everything that should be done is not needed or just cosmetics. ✌️ ☮️

[yukarpenko]

By the cosmetic changes, I meant that the improvements to the code that you've listed are not supposed not change at all the way the computations are done. It's still same old algorithm from 10+ years ago, which can be improved - that's what I mean by physics changes. Maybe the wording sounds a bit disrepectful, sorry if it is like that. I would be happy to see a better code, but again I would be happy to discuss what's your (or someone's) idea about improving the core, not just the handling of inputs/outputs. If there's one. Or whether anyone is interested in such a project.
(By the way, the current (or recent) test that was introduced in the code I would consider more of a placeholder, since it doesn't really test anything, if you know what is actually important in the algorithm.)
May be better if we chat over zoom - last week of July onwards (I am on holidays now). I understand your arguments, but things may look (and they do look) very differently outside of ... your group, basically. In any case, I would explain more over zoom. I think there's quite some misunderstanding of what I was taking about, but since I am not in Frankfurt, I can guess why there's so much misunderstanding.
BTW since you have mentioned the wrong things in implementation, I would also discuss this over zoom, by looking at the past pull requests, and explaining my view on them.
So, please let me know about the zoom chat.

[yukarpenko]

So i appreciate the items in the list that you've outlined, but it is not the only updates that will have to be done. and for the "other" updates I need to understand the broader picture, I think.