Docstring formatting
39 views
Skip to first unread message
gmou3
Jun 22, 2024, 4:25:43 AM (11 days ago) Jun 22
to sage-devel
Hi all,
I am working on a large scale docstring formatting PR (https://github.com/sagemath/sage/pull/38155), and I invite you to come and share your opinions and help with the review process.
Some comments from me, from things that I've noticed:
There are many inconsistencies in formatting and trivial syntactical/grammatical errors. It may be my own sensibilities, but this exudes a lack of professionalism which undermines the whole Sage project. This I believe is not solely an aesthetic issue: a more professional appearance can inspire more serious work from users and developers. It also makes later decisions and changes in style more easily applicable.
My recommendations are the following:
1. Reach a decision upon all matters of style;
I am working on a large scale docstring formatting PR (https://github.com/sagemath/sage/pull/38155), and I invite you to come and share your opinions and help with the review process.
Some comments from me, from things that I've noticed:
There are many inconsistencies in formatting and trivial syntactical/grammatical errors. It may be my own sensibilities, but this exudes a lack of professionalism which undermines the whole Sage project. This I believe is not solely an aesthetic issue: a more professional appearance can inspire more serious work from users and developers. It also makes later decisions and changes in style more easily applicable.
My recommendations are the following:
1. Reach a decision upon all matters of style;
2. Write a script to enforce a consistent style (a new CI test).
Reply all
Reply to author
Forward
0 new messages