Argument Clinic should add markers for humans

[pitrou]

BPO	19723
Nosy	@gvanrossum, @ncoghlan, @pitrou, @larryhastings, @skrah, @serhiy-storchaka
Files	larry.change.clinic.markers.diff.1.txt

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/larryhastings'
closed_at = <Date 2014-01-07.20:43:42.614>
created_at = <Date 2013-11-22.20:04:04.964>
labels = ['type-bug', 'build']
title = 'Argument Clinic should add markers for humans'
updated_at = <Date 2014-01-07.22:25:57.662>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2014-01-07.22:25:57.662>
actor = 'python-dev'
assignee = 'larry'
closed = True
closed_date = <Date 2014-01-07.20:43:42.614>
closer = 'larry'
components = ['Build', 'Demos and Tools']
creation = <Date 2013-11-22.20:04:04.964>
creator = 'pitrou'
dependencies = []
files = ['33343']
hgrepos = []
issue_num = 19723
keywords = []
message_count = 24.0
messages = ['203852', '203858', '203864', '203869', '203899', '204025', '207480', '207481', '207482', '207485', '207486', '207487', '207488', '207490', '207491', '207492', '207493', '207528', '207529', '207541', '207550', '207591', '207607', '207611']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'ncoghlan', 'pitrou', 'larry', 'skrah', 'python-dev', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue19723'
versions = ['Python 3.4']

[pitrou]

I was reviewing a patch by Larry and I started commenting on some rather tasteless code, until I realized it was generated by Argument Clinic.

It would be nice if Argument Clinic added some markers, such as:

/* Start of code generated by Argument Clinic */

/* End of code generated by Argument Clinic */

[larryhastings]

You find the big
/[clinic checksum: b6ded2204fd0aab263564feb5aae6bac840b5b94]/
marker insufficient?

Perhaps this is simply something we will quickly get used to. How about we let this sit for a while and see what other people think.

p.s. I accept your critique of Clinic's autogenerated code.

[pitrou]

You find the big
/[clinic checksum: b6ded2204fd0aab263564feb5aae6bac840b5b94]/
marker insufficient?

Well, it doesn't say anything except "checksum", and it doesn't seem
geared at humans (except perhaps those with a hex calculator in their
head :-)).

Clinic-generated code looks at first sight like code that would be
written by a human, so it's easy to get miffed.

[skrah]

I think it's possible to get used to the markers. However, to bikeshed a
little, I would prefer "preprocessor" instead of "clinic", since jokes
tend to wear off if one sees then too often.

[larryhastings]

However, to bikeshed a little, I would prefer
"preprocessor" instead of "clinic", since jokes
tend to wear off if one sees then too often.

"Argument Clinic" is the name of the tool. The marker /[clinic]/
was chosen deliberately:

• If someone says "what the hell is this" a quick online search
  should turn up the answer quickly.

• It differentiates it from /[python]/, which allows one to embed
  raw Python code inside files. ("print" is redirected to the output
  section.)

[ncoghlan]

On 23 Nov 2013 08:05, "Larry Hastings" <report@bugs.python.org> wrote:

Larry Hastings added the comment:

> However, to bikeshed a little, I would prefer
> "preprocessor" instead of "clinic", since jokes
> tend to wear off if one sees then too often.

"Argument Clinic" is the name of the tool. The marker /[clinic]/
was chosen deliberately:

• If someone says "what the hell is this" a quick online search
  should turn up the answer quickly.

• It differentiates it from /[python]/, which allows one to embed
  raw Python code inside files. ("print" is redirected to the output
  section.)

It also differentiates it clearly from the C preprocessor. If Guido can
name the language after a comedy troupe, Larry can certainly name the
custom code generator after one of their sketches :)

FWIW, I tend to start editing the generated code as well, so I agree this
is something for us to keep an eye on. If the habit doesn't go away, we may
want some more prominent markers.

Cheers,
Nick.

----------

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue19723\>

---

[gvanrossum]

I grepped for clinic in the source code and I have a hunch why this confusing: each clinic-generated block has *three* marker comments, each containing [clinic] or [clinic checksum: ...].

TBH I can't always tell on which side of the comment the generated code sits, so I agree it would be nice if there was an additional keyword clearly indicating begin/end.

Looking more carefully it seems the pattern is

/[clinic]
.
. (this seems to be the clinic input)
.
[clinic]/
.
. (this seems to be generated)
.
/[clinic checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]/

I expect things would be clearer to the uninitiated if instead they said something like:

/[clinic input]
.
.
.
[clinic start generated code]/
.
.
.
/[clinic end generated code; checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]/

Larry, would that be easy?

[larryhastings]

And for Python blocks would you suggest

/[python input]
...
[python start generated code]/
...
/[python end generated code; checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]/

To answer your question: no, it wouldn't be hard.

[gvanrossum]

Yes. Then I suggest working on a patch before people get too deep into the conversion project.

[serhiy-storchaka]

Why not just move most (except implementation function headers) generated code out to separate file? Right now the list of symbols in the Kate editor contains three names for every function: BINASCII_A2B_UU_METHODDEF, binascii_a2b_uu and binascii_a2b_uu_impl. This makes navigation cumbersome. Also when I search function name
a2b_uu, I found 13 occurrences (it will be decreased to 2 or 3 if move generated code out). So search is not helpful too,

[gvanrossum]

I use Emacs, so I have no idea what would help for Kate. I suppose Kate is programmable? Maybe you can add some kind of filter for this purpose?

If e.g. binascii_a2b_uu_impl were moved to a different file, how would binascii_a2b_uu call it without exposing the symbol externally?

[pitrou]

If e.g. binascii_a2b_uu_impl were moved to a different file, how would
binascii_a2b_uu call it without exposing the symbol externally?

I think "stitching it with #include" is the only workable solution.
We already do this for e.g. stringlib.