Code style, linting and developer experience

[crnh]

Hi! I just opened my first pull request in this repo. Generally speaking, it was a nice experience: clear contributing guidelines, well-written and understandable code - thanks for that! I would like to give some feedback on the first point of the guidelines: "Follow the existing coding style." I agree that it is important to maintain a consistent style throughout the project, but how do I know what style I should maintain? I couldn't find any documentation about that, and if I need to infer it from the code base, my conclusions will probably differ from your ideas.

In my opinion, Optiland's code quality would benefit from making the code style less subjective, for example by using a linter and a formatter. Among many different tools, Ruff is a popular option that serves both as a linter and a formatter. Using a formatter, you can automatically enforce and apply a predefined code style. For me, that's one thing less to worry about.

I advise to take this a step further and use a project manager for all development-related tasks, so not only formatting and linting, but also testing (against multiple Python versions), building docs, and running other commands. Again, there are many tools available, for example Hatch, PDM, Pipenv and Poetry. In my personal projects, I mostly use Hatch for this purpose, because it comes with built-in testing functionality (hatch test, using Pytest) and a formatter (hatch fmt, using Ruff). You can check an example setup at MREYE-LUMC/ZOSPy (make sure you pick the v2.0.0 branch).

Whichever tools you pick, I think automating these tasks would significantly improve the developer experience and the code quality!

[HarrisonKramer]

Hi @crnh,

Thanks for taking the time to review Optiland and provide suggestions! Your feedback on clarifying the style, and automating it, is very much welcome.

I agree that the guideline "Follow the existing coding style" is quite vague. I think it makes sense to add some clarifications in the docs here, at least for high-level expectations for "following the existing style". I will plan to update this.

I have not used Ruff, nor Hatch, but I will definitely take a look. I am always interested in ways to make the code quality better, as well as lower the "barrier for entry" for users who may want to extend the codebase or add some functionality. I am currently using GitHub Actions for many tasks (testing, coverage checks, pypi publishing, doc generation). I need to familiarize myself with Ruff/Hatch to see how it might fit into the current workflow. I will study these a bit and take a deeper look at the ZOSPy example!

If you have any other suggestions to make Optiland better, feel free to share. Thanks again.

Regards,
Kramer