[Python-ideas] Custom Code Folding: Standardized Rules and Syntax?

[Brice PARENT]

Hi Connor,

I'm also a Pycharm user (Professional edition for me, but I'm not sure 
it changes anything here).

I didn't know about this functionality (if you're referring to this : 
https://www.jetbrains.com/help/pycharm/code-folding.html#using_folding_comments 
at least):

|//region Description
...
//endregion|

But in general, I'm not a fan of having those type of meta-comments: 
they don't document the code or help understanding what it's doing, they 
just help those who happen to use an IDE that implemented this and who 
know what this means. And the help it gives is not to show something, 
but to hide it. For the other ones, it's just polluting the file with 
nonsensical (to their eyes) words.

Another aspect that I'm worried about when inserting things that don't 
really belong to the code: it will be commited with the rest of the 
code. And if you added those comments because it helped you during the 
development of a special part of the file, it will still get pushed to 
the repository whether it is still useful or not. And if it's not, it 
will cost another commit to clean up, along with many potential 
cascading and maybe automatic things (pull-request, unit-tests, build, 
push to production which can be a huge thing if it's shared between many 
servers and services for example). All for a comment that might be only 
usable with some IDEs, and maybe even only useful during 4 hours for a 
single developer.

But...

That doesn't mean that the functionality isn't useful. The IDE could 
manage an external gitignorable file containg metadata about which parts 
of the code could be folded as a pack. If there are many people who want 
this, they might consider implementing it. But I don't believe this 
should be implemented at Python's level. Code folding feels to me like 
something some of us may want while some others may not, or not in the 
same cases.

If I'm off topic (I might not have understood it very well), don't 
hesitate to tell me. And to provide examples!

-Brice


Le 16/07/17 à 16:37, Connor Farrell a écrit :
> 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.
> - 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. 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. My IDE doesn't yet offer to 
> fold long parameter lists by default, but I think it makes sense.
>
> 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.
>
> 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.
>
> Cheers
>
>
>
> _______________________________________________
> 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/de960160/attachment-0001.html>