[issue30440] document peephole optimizer effects

[Raymond Hettinger]

Raymond Hettinger added the comment:

Thanks Emily.  

This should be probably be a FAQ entry (cpython/Doc/faq) because the peephole optimizer is a CPython implementation detail, because we don't normally document internal details such as which opcodes are generated or big-oh runtimes etc, because isn't really a good place for this elsewhere, and because the low level details are frequently changing.

Ideally, the FAQ entry should be brief and focus on the two user visible effects. 1) The jump-to-jump optimization can cause a coverage analysis tool to mark as uncovered a line that is logically executed but is bypassed because it has no effect.  2) Constant folding transfers run-time costs to compile-time costs -- this may matter when the expression is expensive to compute or if it results in the creation of a large object.

Follow the documentation advice given in the dev guide:
* https://docs.python.org/devguide/documenting.html#affirmative-tone
* https://docs.python.org/devguide/documenting.html#economy-of-expression
* https://docs.python.org/devguide/documenting.html#audience

The key part of the first link is to keep it upbeat, focusing on what the tool does, the related costs and benefits, and giving recommendations on how to control it.  We don't want the docs to read as a litany of warnings and suggestions of danger.

In particular, I recommend discussing the OP's compute_largest_known_prime() example and explaining:
1) the intended calculation is expensive in terms of both space and time 
2) the constant folding step of code generation does this computation at compile-time
3) since this computation is slow, it noticeably slows down the compilation (appears to hang at compile-time rather than at run-time as it normally would)
4) since this computation creates a large object, the pyc file will be large
5) due to pre-computation, the run-time call will be fast
6) if that effect is not desired, it is easily turned-off by storing part of the expression in a variable:
    >>> def compute_largest_known_prime():
    ...     exp = 74207281
    ...     return 2 ** exp - 1

The key part of the second link is to be brief and terse.  It would be easy to write an entire blog post or chapter in a book about constant folding, but that wouldn't be efficient with the reader's time or really help them out in a meaningful way.

The key part of the third link is address what you think is helpful to new readers of the FAQ who don't already understand the issue.  We don't make doc entries to appease or vindicate someone.  The docs aren't a vehicle for expressing opposition to design decision; instead, it is a place to explain what the tools do and how to use them.

Try not to over-specify the implementation.  Note that constant folding takes place but don't guarantee specific transformations.  These are all subject to change, have changed over time (including backports), and changing even now.

----------
assignee: docs at python -> emilyemorehouse

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue30440>
_______________________________________