Hi, I made multiple changes to the Include/abstract.h header file, because it was inconsistent in different manners: * Parameter names of functions of the PyObject_Call family were inconsistent: "func" versus "callable" for a Python callable object for example (sometimes, .c and .h files were inconsistent too) * Only this header file used an indentation of 4 spaces in the whole space * Only this header used comments *after* the function declaration and with a newline between the comment and the declaration. Other headers use a comment *before* the declaration and no newline. * Some comments were far (100 lines) from function declaration, so it wasn't possible anymore to understand these comments. * Other tiny changes Before: https://hg.python.org/cpython/file/f692dafe6797/Include/abstract.h Now: https://hg.python.org/cpython/file/c4bcca326c0a/Include/abstract.h (Not sure that it's easy to compare such long header file, ~1 200 lines, in a web browser.) See http://bugs.python.org/issue28838 for more information. Serhiy Storchaka was opposed to these changes, some extract of his comments: * "Isn't this just a lot of churn for not a lot of benefit?" - Eric V. Smith asked the same question * "It breaks "hg annotation" and makes harder researching the history of the file" I already pushed all my changes anyway, but Serhiy asked me to discuss these changes on Python-Dev, so here I am. I decided to cleanup abstract.h because I had to modify it multiple times last 2 years, especially when I added new functions for fast calls, and I was always surprised and confused by the style of header. I didn't know how to format my code, and it seems like I also introduced some inconsistent coding style in the newly added code. For the first change that I made recently, normalizing parameter names, I first pushed directly a change without review, but Serhiy asked me on this list to revert it. So I reverted the change and continued the discussion on the issue #28838. We agreed on better names, and so I pushed a different change. Victor
I think it looks better. Thank you. On Thu, Dec 15, 2016, at 02:22, Victor Stinner wrote:
Hi,
I made multiple changes to the Include/abstract.h header file, because it was inconsistent in different manners:
* Parameter names of functions of the PyObject_Call family were inconsistent: "func" versus "callable" for a Python callable object for example (sometimes, .c and .h files were inconsistent too)
* Only this header file used an indentation of 4 spaces in the whole space
* Only this header used comments *after* the function declaration and with a newline between the comment and the declaration. Other headers use a comment *before* the declaration and no newline.
* Some comments were far (100 lines) from function declaration, so it wasn't possible anymore to understand these comments.
* Other tiny changes
Before: https://hg.python.org/cpython/file/f692dafe6797/Include/abstract.h
Now: https://hg.python.org/cpython/file/c4bcca326c0a/Include/abstract.h
(Not sure that it's easy to compare such long header file, ~1 200 lines, in a web browser.)
See http://bugs.python.org/issue28838 for more information.
Serhiy Storchaka was opposed to these changes, some extract of his comments:
* "Isn't this just a lot of churn for not a lot of benefit?" - Eric V. Smith asked the same question * "It breaks "hg annotation" and makes harder researching the history of the file"
I already pushed all my changes anyway, but Serhiy asked me to discuss these changes on Python-Dev, so here I am.
I decided to cleanup abstract.h because I had to modify it multiple times last 2 years, especially when I added new functions for fast calls, and I was always surprised and confused by the style of header. I didn't know how to format my code, and it seems like I also introduced some inconsistent coding style in the newly added code.
For the first change that I made recently, normalizing parameter names, I first pushed directly a change without review, but Serhiy asked me on this list to revert it. So I reverted the change and continued the discussion on the issue #28838. We agreed on better names, and so I pushed a different change.
Victor _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/benjamin%40python.org
On Thu, 15 Dec 2016 11:22:10 +0100
Victor Stinner
Before: https://hg.python.org/cpython/file/f692dafe6797/Include/abstract.h
Now: https://hg.python.org/cpython/file/c4bcca326c0a/Include/abstract.h
Since you are cleaning up, you could remove the whole "PROPOSAL: A Generic Python Object Interface for Python C Modules" introduction, which isn't very interesting to read today. Regards Antoine.
2016-12-16 11:24 GMT+01:00 Antoine Pitrou
Since you are cleaning up, you could remove the whole "PROPOSAL: A Generic Python Object Interface for Python C Modules" introduction, which isn't very interesting to read today.
Ah right, I noticed this huge comment but I didn't understand the purpose. IMHO https://docs.python.org/dev/c-api/ is now a much better documentation for the Python C API. I agree to remove the long introduction. By the way, I'm surprised by the "many thanks to Jim Fulton" in the comment, since I'm not sure to what it is referred to. But in case of doubt, I prefer to keep it :-) /* Abstract Object Interface (many thanks to Jim Fulton) */ Victor
Many eons ago, Jim created abstract.h. The proposal comment (which you're
right to be cutting out now) was his and at some point it was accepted, but
I just copied-pasted the whole text into abstract.h. So yes, please keep
the "many thanks to Jim Fulton" in there!
On Fri, Dec 16, 2016 at 7:03 AM, Victor Stinner
2016-12-16 11:24 GMT+01:00 Antoine Pitrou
: Since you are cleaning up, you could remove the whole "PROPOSAL: A Generic Python Object Interface for Python C Modules" introduction, which isn't very interesting to read today.
Ah right, I noticed this huge comment but I didn't understand the purpose. IMHO https://docs.python.org/dev/c-api/ is now a much better documentation for the Python C API. I agree to remove the long introduction.
By the way, I'm surprised by the "many thanks to Jim Fulton" in the comment, since I'm not sure to what it is referred to. But in case of doubt, I prefer to keep it :-)
/* Abstract Object Interface (many thanks to Jim Fulton) */
Victor _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ guido%40python.org
-- --Guido van Rossum (python.org/~guido)
2016-12-16 11:24 GMT+01:00 Antoine Pitrou
Since you are cleaning up, you could remove the whole "PROPOSAL: A Generic Python Object Interface for Python C Modules" introduction, which isn't very interesting to read today.
Done: hg.python.org/cpython/rev/3ab0a6692e25 Victor
participants (4)
-
Antoine Pitrou
-
Benjamin Peterson
-
Guido van Rossum
-
Victor Stinner