Custom Code Folding: Standardized Rules and Syntax?
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
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
On 16/07/17 16:15, Steven D'Aprano wrote:
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. 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?
The usual mechanism for folding (in those editors that don't think they know best) is to delimit them with comments that start with a particular sequence of characters. You might have: class Shrubbery: def __init__(self, size, planting, rockery=False): # {{{ Boring bits you don't need to see self.size = size self.rockery = rockery # }}} self.cost = complicated_function_of(planting) ...and so on.
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.
I think I do understand the proposal, but I still agree with Steven. Folding is a feature of IDEs, not languages, and trying to legislate about it in a language definition is a bad plan. I say this as someone who wrote a folding editor to make programming in Occam bearable :-) -- Rhodri James *-* Kynesim Ltd
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_comme... 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@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
participants (4)
-
Brice PARENT -
Connor Farrell -
Rhodri James -
Steven D'Aprano