<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>Sorry I didn't see this answer (as the title changed, it was
moved to another topic in my mailbox).</p>
<p>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.</p>
<p>It can be as chapters or sub-chapters, which might be a nice
organization of the code.<br>
</p>
<p>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, ...).</p>
<p>So the IDE just need to parse those comments and implement a code
folding method based on it. <br>
</p>
<p>It could simply be `### [description]`, like `### Security
features`.</p>
<p>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).<br>
</p>
<p>But there are downsides:</p>
<p>- 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.</p>
<p>- 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?</p>
<p>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!).<br>
</p>
<p>-Brice<br>
</p>
<br>
<div class="moz-cite-prefix">Le 16/07/17 à 18:42, Connor Farrell a
écrit :<br>
</div>
<blockquote type="cite"
cite="mid:CAL5Ag8RR9a-+Gr0mNjpc0ou4npAh1xZFKsT2=1BkZu-3Pa6GEA@mail.gmail.com">
<div dir="ltr">
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>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 <i>typing</i>
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:<br>
<br>
</div>
class A:<br>
</div>
<div> #<< INTERFACE<br>
</div>
def foo():<br>
....<br>
</div>
def bar():<br>
....<br>
#>><br>
<br>
</div>
<div> #<< BACKEND<br>
</div>
def _guts():<br>
....<br>
#>><br>
<br>
</div>
Would become something like:<br>
<br>
</div>
class A:<br>
</div>
<b>>+ INTERFACE<br>
<br>
</b></div>
<b> >+ BACKEND<br>
<br>
</b></div>
<div>Where <b>modern</b> 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:<br>
<br>
</div>
<div>def func(f: Callable[[float],float, float]) -> None:<br>
</div>
<div> <b>>+</b> <b>Input validation</b><br>
</div>
<div><br>
</div>
<div> <b>>+ Some complex algorithm<br>
</b></div>
<div><b><br>
</b></div>
<div><b> >+ Some other complex algorithm<br>
<br>
</b></div>
<div><b> >+ Generating plot<br>
</b></div>
<div><b><br>
</b></div>
<div>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. <br>
</div>
<div><b><br>
</b></div>
<div><b> <br>
</b></div>
<div><b><br>
</b></div>
<br>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div><br>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Sun, Jul 16, 2017 at 12:00 PM, <span
dir="ltr"><<a
href="mailto:python-ideas-request@python.org"
target="_blank" moz-do-not-send="true">python-ideas-request@python.org</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">Send
Python-ideas mailing list submissions to<br>
<a href="mailto:python-ideas@python.org"
moz-do-not-send="true">python-ideas@python.org</a><br>
<br>
To subscribe or unsubscribe via the World Wide Web, visit<br>
<a
href="https://mail.python.org/mailman/listinfo/python-ideas"
rel="noreferrer" target="_blank" moz-do-not-send="true">https://mail.python.org/<wbr>mailman/listinfo/python-ideas</a><br>
or, via email, send a message with subject or body 'help' to<br>
<a href="mailto:python-ideas-request@python.org"
moz-do-not-send="true">python-ideas-request@python.<wbr>org</a><br>
<br>
You can reach the person managing the list at<br>
<a href="mailto:python-ideas-owner@python.org"
moz-do-not-send="true">python-ideas-owner@python.org</a><br>
<br>
When replying, please edit your Subject line so it is more
specific<br>
than "Re: Contents of Python-ideas digest..."<br>
<br>
<br>
Today's Topics:<br>
<br>
1. Re: Custom Code Folding: Standardized Rules and
Syntax?<br>
(Steven D'Aprano)<br>
<br>
<br>
------------------------------<wbr>------------------------------<wbr>----------<br>
<br>
Message: 1<br>
Date: Mon, 17 Jul 2017 01:15:59 +1000<br>
From: Steven D'Aprano <<a
href="mailto:steve@pearwood.info" moz-do-not-send="true">steve@pearwood.info</a>><br>
To: <a href="mailto:python-ideas@python.org"
moz-do-not-send="true">python-ideas@python.org</a><br>
Subject: Re: [Python-ideas] Custom Code Folding:
Standardized Rules<br>
and Syntax?<br>
Message-ID: <<a
href="mailto:20170716151559.GW3149@ando.pearwood.info"
moz-do-not-send="true">20170716151559.GW3149@ando.<wbr>pearwood.info</a>><br>
Content-Type: text/plain; charset=us-ascii<br>
<br>
Hi Connor, and welcome!<br>
<br>
On Sun, Jul 16, 2017 at 10:37:26AM -0400, Connor Farrell
wrote:<br>
> Background: I work in scientific computing and use
Community Pycharm IDE.<br>
><br>
> I'm a religious follower of the 'readability counts'
mantra, and two things<br>
> I find myself doing often are:<br>
> - Writing custom code folds to segregate code, from
groups of classes in a<br>
> file, to groups of lines in an individual function.
While spacing works<br>
> great to separate ideas, my IDE allows me to collapse
the entirety of the<br>
> code in exchange for a line of English. For my
purposes, this enhances<br>
> readability immensely, as first time users are
confronted with an<br>
> explanation of the contents, rather than the code
itself with a comment on<br>
> top. I find comments don't draw the eye, and also don't
have the ability to<br>
> their code as well.<br>
<br>
I'm afraid I'm having a lot of difficulty understanding
this. I think<br>
the last sentence is missing a word. Comments don't have the
ability to<br>
**what** their (whose?) code?<br>
<br>
Which IDE are you using? When you say it collapses the
"entirety of the<br>
code", do you mean the entire file?<br>
<br>
<br>
> - Writing high level code, such as __init__ calls for
large aggregates,<br>
> with one keyworded argument per line (plus dict
unpackings at the end),<br>
> sort of like a simple XML file.<br>
<br>
Even if I accept that this is a reasonable design for
__init__, I would<br>
not agree that it is a reasonable design for "high level
code" in<br>
general.<br>
<br>
<br>
> This allows me to make parameters explicit<br>
> for other users, and optionally provide a comment
indicating physical<br>
> units, cite sources, and/or give a list of tag/enum
options for every<br>
> parameter. In the end I have 30+ line inits, but the
readability is 10x<br>
> greater.<br>
<br>
Perhaps I might be convinced if I saw some actual code, but
from your<br>
description alone, it doesn't sound particularly more
readable. Why<br>
would I want to read citations in the parameter list of a
method? I want<br>
to call the method, not do peer review on the theory behind
it.<br>
<br>
<br>
> My IDE doesn't yet offer to fold long parameter lists
by default,<br>
> but I think it makes sense.<br>
<br>
*shrug*<br>
<br>
Personally, I don't find code folding a big help. Perhaps
once in a blue<br>
moon. I'm glad you like it and that it helps you.<br>
<br>
<br>
> In the end, I end up with very well folded code (except
for large parameter<br>
> lists) and a bunch of co-workers asking about all the
"editor-fold"<br>
> comments that don't work in their API.<br>
<br>
I'm afraid I'm not understanding you here either. What's an<br>
"editor-fold" comment? What do they mean by API? API for
which<br>
application? How does the programming interface to an
application relate<br>
to code folding in a text editor?<br>
<br>
<br>
> Python was a trail-blazer in terms of emphasizing the
importance of code<br>
> readability and effective syntax. I think that we
should consider some sort<br>
> of standard for folding comments, if not only to
promote stronger code<br>
> organizations. I know standards don't usually interact
with IDEs, but hey,<br>
> the 'typing' module is pretty dang nice.<br>
><br>
> TL;DR: Code folding is great, custom code folding is
great, let's upgrade<br>
> it to a language feature.<br>
<br>
What does that even mean? Are you suggesting that the Python
interpreter<br>
should raise a SyntaxError or something if your code was
written in an<br>
editor that didn't support code folding? How would it know?<br>
<br>
Python is a programming language. The source code is text. I
should be<br>
able to write Python code in NotePad if I want. Why should
the Python<br>
core devs try to force every text editor and IDE fold code
exactly the<br>
same way? That sounds awful to me. People choose different
editors<br>
because they like different features, and that may include
the<br>
particular way the editor folds code. Or to not fold it at
all.<br>
<br>
I'm sorry to be so negative, but I don't understand your
proposal, and<br>
the bits that I *think* I understand sound pretty awful to
me. Perhaps<br>
you can explain a bit better what you mean and why it should
be a<br>
language feature, apart from "I want everyone to lay out
their source<br>
code the way I do". Because that's what it sounds like to
me.<br>
<br>
<br>
--<br>
Steve<br>
<br>
<br>
------------------------------<br>
<br>
Subject: Digest Footer<br>
<br>
______________________________<wbr>_________________<br>
Python-ideas mailing list<br>
<a href="mailto:Python-ideas@python.org"
moz-do-not-send="true">Python-ideas@python.org</a><br>
<a
href="https://mail.python.org/mailman/listinfo/python-ideas"
rel="noreferrer" target="_blank" moz-do-not-send="true">https://mail.python.org/<wbr>mailman/listinfo/python-ideas</a><br>
<br>
<br>
------------------------------<br>
<br>
End of Python-ideas Digest, Vol 128, Issue 41<br>
******************************<wbr>***************<br>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Python-ideas mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Python-ideas@python.org">Python-ideas@python.org</a>
<a class="moz-txt-link-freetext" href="https://mail.python.org/mailman/listinfo/python-ideas">https://mail.python.org/mailman/listinfo/python-ideas</a>
Code of Conduct: <a class="moz-txt-link-freetext" href="http://python.org/psf/codeofconduct/">http://python.org/psf/codeofconduct/</a>
</pre>
</blockquote>
<br>
</body>
</html>