Interested in code QA ?

[fralau]

See issue #29

[fralau]

@ultrabug Would you like to expand on this topic?

[fralau]

Thanks a lot! Consider that I have no idea about this yet, so you can start explaining from scratch 🙂

[ultrabug]

• isort: Python utility / library to sort imports alphabetically, and automatically separated into sections and by type -- fixes imports for us in a deterministic way
• black: the PSF backed uncompromising Python code formatter -- no matter who writes the code, it will be formatted the same
• flake8: checks for PEP8 and more -- we're interested in the more here since formatting is done by black; but flake8 when configured right will tell us things like unused variables, variable shadowing etc...

The combination of the 3 gives you a sane base of consistent code + minimal but useful code analysis for obvious mistakes 👍

[fralau]

Thanks a lot for this description, as I didn't know these interesting tools!

It seems to me that they are designed for the form of the code. I see how having orderly imports, well formatted code, or pointers to unused/shadowed variables can help.

However, I tend to put function over form, because when function becomes sufficiently good, it will always take care of the form.

In programming, good form is whatever pattern functions well, consistently and sustainably.

Conversely whatever works well, consistently and sustainably, is good form, by definition.

Imports

For imports, I am visually sorting all imports at the top of a .py file into four functional categories:

1. Standard "out-of-the box" libraries
2. Common packages (from pypi...)
3. In-house packages
4. Calls to modules of the same package

This seems a better approach, to me, than an alphabetical sort: since I can immediately track what is used and unused, and decide how sensible the dependencies are, etc.

This is also easy to enforce, since a very quick glance at the source file will tell whether this is done or not. And then, if it is done, it will be easy to follow and track.

Standard formatting

I am not saying that standard formatting has no merits, but I am not aware there is an immediate quality problem with that.

I am trying to follow some common sense rules (line width, etc.). But what I think is far more important, is to write every single line of code so that (ideally) anyone could instantly understand what it does.

As a I said, I value function over structure. If that requires one (in the extreme) to break every formal rule in the book, then the hell with the rules.

The only rules that really can't be broken are lexical and grammar rules.

Unused variables and shadowing

This can be an issue on large projects, with many contributors. For a project of this size, I haven't met a situation where the tools in my IDE (which point out the most obvious points) is really needed.

What would be required at this stage

The real quality assurance problem with a project like mermaid2, and the place where it really breaks down, is functional: automated testing.

mermaid2 uses a whole stack of technologies (from Python, to markdown, HTML, HTTP server, javascript, json, YAML, css, etc.) and the possible breakpoints are many. The mermaid javascript library is a little messy and sometimes finicky for advanced applications.

What I would really like to have is:

Some simple and practical solution to improve the testing of the code, to make sure that the use cases/test cases are properly formalized and tested, each time a new version of the code is committed, or a new version is released.

[ultrabug]

Your project, your rules mate. We all have our own kind of sensibility so I absolutely respect your point of view and opinion.

Ofc having great tests is important, but that was not the scope of my (hopefully) simple proposal :)

Closing issue, thanks again for the time you spent considering this.

[fralau]

@ultrabug Thanks for your input. I was honest in my answer (perhaps too honest?).

Certainly, subjective interests play a role in the development of a project. Necessity is also a powerful driver; particularly the users' list of issues and their feature requests.

I need to thank you for point out these tools to me. Now that I know that they exist, I will know where to go, if the need arises to enforce some formal rules.

[fralau]

IMHO, the real quality assurance problem with a project like mermaid2, and the place where it really breaks down, is functional: automated testing.

mermaid2 uses a whole stack of technologies (from Python, to markdown, HTML, HTTP server, javascript, json, YAML, css, etc.) and the possible breakpoints are many. The mermaid javascript library is a little messy and sometimes finicky for advanced applications.

What I would really like to have is:

Some simple and practical solution to improve the testing of the code, to make sure that the use cases/test cases are properly formalized and tested, each time a new version of the code is committed, or a new version is released.

[ultrabug]

Yep I understand and don't worry I closed the original issue not because you were too honest (one can never be enough) but because I don't like having issues opened where upstream does not want to move forward.

Thanks again mate 👍

[jakob1379]

on this topic, would you be interested in some help simplifying the packaging and release cycle? Python has come a long way and packaging/releasing has become a one-liner uv publish

I would gladly help out migrating to a simpler setup.

[fralau]

Hello, and certainly I could do with some help with packaging/testing/releasing.
In more detail, what would be your idea?

[jakob1379]

migrate to uv as your interface for project management. It makes your life so much easier.

this will let you remove:

• setup.py (usually migrated to 2 lines in pyproject.toml)
• The custom release script can be migrated to a github ci workflow that automatically releases to pypi when you make a semver tag

I have used this in other similar projects and it is less lines that exists in the current codebase. The semver release cycle makes it easy to choose, when you want to release, instead of releasing on every merge to main.

[fralau]

Thanks! On one hand, setup.py is already removed (replaced by pyproject.toml).

I have started using uv myself on another project, and you are right, it is an interesting tool.
If someone could write a github ci, it would also be a good idea. 🤔

[jakob1379]

setup.py is still in the root :)

ill make a pr then, and we can continue any discussion there 👍