[Python-ideas] Python-ideas Digest, Vol 128, Issue 41

David Mertz mertz at gnosis.cx
Sun Jul 16 14:57:15 EDT 2017 

Many editors allow you to explicitly select blocks to fold rather than only
basing it on explicit syntax in a code file. Obviously, the information on
where those folds occurred is them generally stopped somewhere apart from
the text of the code itself. It sounds like you should choose an editor
that does that and/or a macro/extension/mode to your favorite editor to
behave as you like.

On Jul 16, 2017 11:27 AM, "Brice PARENT" <contact at brice.xyz> wrote:

> Sorry I didn't see this answer (as the title changed, it was moved to
> another topic in my mailbox).
>
> So I still believe code-folding indications don't really belong to the
> source files. But what you're showing is interesting, and the code folding
> is just a consequence of it.
>
> It can be as chapters or sub-chapters, which might be a nice organization
> of the code.
>
> I'm not sure of the relevance of the closing code though: If they are like
> chapters, they describe the content until the next chapter, or until the
> scope ends (end of method, of function, of class, ...).
>
> So the IDE just need to parse those comments and implement a code folding
> method based on it.
>
> It could simply be `### [description]`, like `### Security features`.
>
> I think it could be a good help in some cases, like in a settings.py files
> (like Django's one which can be pretty long).
>
> But there are downsides:
>
> - We should try to avoid to write classes, methods or functions that are
> too long. It often means that it should be split into smaller
> functionalities. This would probably not push the developers in the right
> direction if we asked them to used such a tool. But I don't know if this
> big-pieces-of-code-is-a-code-smell-for-refactorisation is true for
> scientific development, as I imagine there can be some quite long pieces of
> codes that really are meant to be together.
>
> - It still enforces a way of coding. Some prefer to group their methods by
> functionality (everything related to security is in grouped for example),
> but others prefer to sort their methods alphabetically. Or by type of
> methods (higher level methods first, lower level last), etc. Also, what
> about magic methods, or methods that are shared between two or more
> functionalities?
>
> So I'm not sure how I feel about this, the discussion and examples may be
> interesting (more than what I understood from first mail anyway!).
>
> -Brice
>
> Le 16/07/17 à 18:42, Connor Farrell a écrit :
>
> Thanks for your feedback, I guess I was a little unclear. In short, I was
> thinking of a pair of comment tokens (something like #<<, #>>, idk) that
> would indicate a code fold, like what virtually all IDEs do for classes and
> methods, but with more granularity. It would allow devs to better organize
> their code. I agree with what you're saying about separation of language
> and text editor, but we already have the *typing* module in 3.6, so
> improved linting and communication is apparently game. I have no desire to
> get the interpreter involved, this is pure linter. A good example would be
> something like:
>
> class A:
>     #<< INTERFACE
>     def foo():
>         ....
>     def bar():
>         ....
>     #>>
>
>     #<< BACKEND
>     def _guts():
>         ....
>     #>>
>
> Would become something like:
>
> class A:
>
>
> *>+ INTERFACE *
>
>
> *    >+ BACKEND *
> Where *modern* editors should fold the code. It provides an optional
> additional layer of granularity above the current system, but has no effect
> on behaviour otherwise. It increases visual information density in complex
> functions, large classes, and lets you group classes. It looks stupid with
> only three functions, but at larger sizes, or with complex code, I'd rather
> see:
>
> def func(f: Callable[[float],float, float]) -> None:
>     *>+* *Input validation*
>
>
> *>+ Some complex algorithm *
>
>
>
> *    >+ Some other complex algorithm *
>
> *    >+ Generating plot *
>
> It adds a human explanation of the code within, an additional level(s) of
> organization, and easier navigation. It's not for everyone, but I feel like
> it improves on the idea of modular code at for active devs, without any
> drawbacks for library users.
>
>
>
>
>
>
>
> On Sun, Jul 16, 2017 at 12:00 PM, <python-ideas-request at python.org> wrote:
>
>> Send Python-ideas mailing list submissions to
>>         python-ideas at python.org
>>
>> To subscribe or unsubscribe via the World Wide Web, visit
>>         https://mail.python.org/mailman/listinfo/python-ideas
>> or, via email, send a message with subject or body 'help' to
>>         python-ideas-request at python.org
>>
>> You can reach the person managing the list at
>>         python-ideas-owner at python.org
>>
>> When replying, please edit your Subject line so it is more specific
>> than "Re: Contents of Python-ideas digest..."
>>
>>
>> Today's Topics:
>>
>>    1. Re: Custom Code Folding: Standardized Rules and Syntax?
>>       (Steven D'Aprano)
>>
>>
>> ----------------------------------------------------------------------
>>
>> Message: 1
>> Date: Mon, 17 Jul 2017 01:15:59 +1000
>> From: Steven D'Aprano <steve at pearwood.info>
>> To: python-ideas at python.org
>> Subject: Re: [Python-ideas] Custom Code Folding: Standardized Rules
>>         and Syntax?
>> Message-ID: <20170716151559.GW3149 at ando.pearwood.info>
>> Content-Type: text/plain; charset=us-ascii
>>
>> Hi Connor, and welcome!
>>
>> On Sun, Jul 16, 2017 at 10:37:26AM -0400, Connor Farrell wrote:
>> > Background: I work in scientific computing and use Community Pycharm
>> IDE.
>> >
>> > I'm a religious follower of the 'readability counts' mantra, and two
>> things
>> > I find myself doing often are:
>> > - Writing custom code folds to segregate code, from groups of classes
>> in a
>> > file, to groups of lines in an individual function. While spacing works
>> > great to separate ideas, my IDE allows me to collapse the entirety of
>> the
>> > code in exchange for a line of English. For my purposes, this enhances
>> > readability immensely, as first time users are confronted with an
>> > explanation of the contents, rather than the code itself with a comment
>> on
>> > top. I find comments don't draw the eye, and also don't have the
>> ability to
>> > their code as well.
>>
>> I'm afraid I'm having a lot of difficulty understanding this. I think
>> the last sentence is missing a word. Comments don't have the ability to
>> **what** their (whose?) code?
>>
>> Which IDE are you using? When you say it collapses the "entirety of the
>> code", do you mean the entire file?
>>
>>
>> > - Writing high level code, such as __init__ calls for large aggregates,
>> > with one keyworded argument per line (plus dict unpackings at the end),
>> > sort of like a simple XML file.
>>
>> Even if I accept that this is a reasonable design for __init__, I would
>> not agree that it is a reasonable design for "high level code" in
>> general.
>>
>>
>> > This allows me to make parameters explicit
>> > for other users, and optionally provide a comment indicating physical
>> > units, cite sources, and/or give a list of tag/enum options for every
>> > parameter. In the end I have 30+ line inits, but the readability is 10x
>> > greater.
>>
>> Perhaps I might be convinced if I saw some actual code, but from your
>> description alone, it doesn't sound particularly more readable. Why
>> would I want to read citations in the parameter list of a method? I want
>> to call the method, not do peer review on the theory behind it.
>>
>>
>> > My IDE doesn't yet offer to fold long parameter lists by default,
>> > but I think it makes sense.
>>
>> *shrug*
>>
>> Personally, I don't find code folding a big help. Perhaps once in a blue
>> moon. I'm glad you like it and that it helps you.
>>
>>
>> > In the end, I end up with very well folded code (except for large
>> parameter
>> > lists) and a bunch of co-workers asking about all the "editor-fold"
>> > comments that don't work in their API.
>>
>> I'm afraid I'm not understanding you here either. What's an
>> "editor-fold" comment? What do they mean by API? API for which
>> application? How does the programming interface to an application relate
>> to code folding in a text editor?
>>
>>
>> > Python was a trail-blazer in terms of emphasizing the importance of code
>> > readability and effective syntax. I think that we should consider some
>> sort
>> > of standard for folding comments, if not only to promote stronger code
>> > organizations. I know standards don't usually interact with IDEs, but
>> hey,
>> > the 'typing' module is pretty dang nice.
>> >
>> > TL;DR: Code folding is great, custom code folding is great, let's
>> upgrade
>> > it to a language feature.
>>
>> What does that even mean? Are you suggesting that the Python interpreter
>> should raise a SyntaxError or something if your code was written in an
>> editor that didn't support code folding? How would it know?
>>
>> Python is a programming language. The source code is text. I should be
>> able to write Python code in NotePad if I want. Why should the Python
>> core devs try to force every text editor and IDE fold code exactly the
>> same way? That sounds awful to me. People choose different editors
>> because they like different features, and that may include the
>> particular way the editor folds code. Or to not fold it at all.
>>
>> I'm sorry to be so negative, but I don't understand your proposal, and
>> the bits that I *think* I understand sound pretty awful to me. Perhaps
>> you can explain a bit better what you mean and why it should be a
>> language feature, apart from "I want everyone to lay out their source
>> code the way I do". Because that's what it sounds like to me.
>>
>>
>> --
>> Steve
>>
>>
>> ------------------------------
>>
>> Subject: Digest Footer
>>
>> _______________________________________________
>> Python-ideas mailing list
>> Python-ideas at python.org
>> https://mail.python.org/mailman/listinfo/python-ideas
>>
>>
>> ------------------------------
>>
>> End of Python-ideas Digest, Vol 128, Issue 41
>> *********************************************
>>
>
>
>
> _______________________________________________
> Python-ideas mailing listPython-ideas at python.orghttps://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
>
>
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20170716/d3491afe/attachment-0001.html>

More information about the Python-ideas mailing list