View source for Code folding

{{Short description|Tool of editors for programming, scripting and markup}}
{{confuse|Constant folding}}
[[File:Vim-folding.png|thumb|upright=1.35|Code folding example on [[PHP]] code with [[vim (text editor)|Vim]]]]
'''Code''' or '''text folding''', or less commonly '''holophrasting''',<ref>Simon Gauvin, Omid Banyasad, "Transparency, holophrasting, and automatic layout applied to control structures for visual dataflow programming languages", in ''Proceedings of the 2006 ACM symposium on Software visualization'', p. 67–75</ref> is a feature of some [[graphical user interfaces]] that allows the user to selectively hide ("fold") or display ("unfold") parts of a document. This allows the user to manage large amounts of text while viewing only those subsections that are currently of interest. It is typically used with documents which have a natural [[tree structure]] consisting of nested elements. Other names for these features include '''expand and collapse''', '''code hiding''', and '''outlining'''. In [[Microsoft Word]], the feature is called "collapsible outlining".

Many user interfaces provide [[disclosure widget]]s for code folding in a sidebar, indicated for example by a triangle that points sideways (if collapsed) or down (if expanded), or by a <code>[-]</code> box for collapsible (expanded) text, and a <code>[+]</code> box for expandable (collapsed) text.

'''Code folding''' is found in [[text editor]]s, [[source code editor]]s, and [[integrated development environment|IDE]]s. The folding structure typically follows the [[Abstract syntax tree|syntax tree]] of the program defined by the [[computer language]]. It may also be defined by levels of [[Indentation style|indentation]], or be specified explicitly using an in-band marker (saved as part of the source code) or out-of-band.

'''Text folding''' is a similar feature used on ordinary text, where the nested elements consist of paragraphs, sections, or [[Outline (list)|outline levels]]. Programs offering this include [[folding editor]]s, [[outliner]]s, and some [[word processor]]s.

'''Data folding''' is found in some [[hex editor]]s and is used to structure a binary file or hide inaccessible data sections.<ref>{{cite web |title=HxD - Freeware Hex Editor and Disk Editor |website=mh-nexus |url=http://mh-nexus.de/hxd/ |accessdate=2007-04-30}}</ref> 

Folding is also frequently used in [[data comparison]], to select one version or another, or only the differences.

==History==
The earliest known example of code folding in an editor is in [[NLS (computer system)|NLS]].<ref>{{Citation|title=The Mother of All Demos, presented by Douglas Engelbart (1968)|url=https://www.youtube.com/watch?v=yJDv-zdhzMY |website=YouTube |last1=Marcel |date=Jul 9, 2012 |language=en|access-date=2019-12-29}}</ref> Probably the first widely available folding editor was the 1974 Structured Programming Facility (SPF) editor for [[IBM System/370|IBM 370]] mainframes, which could hide lines based on their indentation. It displayed on character-mapped 3270 terminals.<ref>{{cite web|access-date=2015-10-27|url=http://planetmvs.com/spfeditor/ispfhist.txt|title=ISPF history |date=25 Jun 1998 |first1=Gilbert |last1=Saint-flour |website=Planet MVS }}</ref> It was very useful for prolix languages like [[COBOL]]. It evolved into the Interactive System Productivity Facility ([[ISPF]]).

==Use==
Code folding has various [[use pattern]]s, primarily organizing code or hiding less useful information so one can focus on more important information. Common patterns follow.{{sfn|Atwood|2008}}

===Outlining===
Most basically, applications use code folding to outline source code, collapsing each block to a single line. This can be only top-level blocks like functions and classes, nested blocks like nested functions and methods, or all blocks, notably control-flow blocks. This allows one to get an overview of code, easily navigating and rearranging it, and to drill down into more detail as needed, without being distracted by other code. Viewing-wise, this allows one to quickly see a list of all functions (without their bodies), while navigation-wise this replaces extensive paging past long functions – or searching for the target – with going directly to the next function.

===Hiding boilerplate code===
Some languages or libraries require extensive [[boilerplate code]]. This results in extremely long code, which can obscure the main point. Further, substantive code can be lost in the boilerplate.

For example, in Java a single private field with a getter and setter requires at least 3 lines, if each is on a separate line:

<syntaxhighlight lang=java>
private String name = null;
public String getName() { return name; }
public void setName(String name) { this.name = name; }
</syntaxhighlight>

This expands to 10 lines with conventional function line breaks and spacing between functions (including trailing newline):

<syntaxhighlight lang=java>
private String name = null;

public String getName() {
    return name;
}

public void setName(String name) {
    this.name = name;
}
</syntaxhighlight>

Documentation with Javadoc expands this to 20 lines:

<syntaxhighlight lang=java>
/**
 * Property <code>name</code>  readable/writable.
 */
private String name = null;

/**
 * Getter for property <code>name</code>
 */
public String getName() {
    return name;
}

/**
 * Setter for property <code>name</code>.
 * @param name
 */
public void setName(String name) {
    this.name = name;
}
</syntaxhighlight>

If there are many such fields, the result can easily be hundreds of lines of code with very little "interesting" content – code folding can reduce this to a single line per field, or even to a single line for all fields. Further, if all routine fields are folded, but non-routine fields (where getter or setter is not just returning or assigning a private field) are not folded, it becomes easier to see the substantive code.

===Collapsing metadata===
Metadata can be lengthy, and is generally less important than the data it is describing. Collapsing metadata allows one to primarily focus on the data, not the metadata. For example, a long list of [[Attribute (computing)|attributes]] in [[C Sharp (programming language)|C#]] may be manually collapsed as follows:<ref>{{Cite web |last=Rob |date=March 19, 2014 |title=Now, this is interesting, because I tend to use #region more to HIDE THE CRAP (XML documentation etc, long list of attributes etc.) making it easier to see the important code… |url=http://discourse.codinghorror.com/t/the-problem-with-code-folding/294/31 |url-status=live |archive-url=https://web.archive.org/web/20200806132848/https://discourse.codinghorror.com/t/the-problem-with-code-folding/294/31 |archive-date=Aug 6, 2020 |website=The Problem With Code Folding |publisher=Coding Horror Discussion}}</ref>

<syntaxhighlight lang="csharp">
#region Attributes
[Browsable(false)]
[MergableProperty(false)]
[DefaultValue(null)]
[PersistenceMode(PersistenceMode.InnerProperty)]
[TemplateContainer(typeof(MyType))]
[TemplateInstance(TemplateInstance.Single)] 
#endregion
public ITemplate ContentTemplate { get; set; }
</syntaxhighlight>

The resulting code displays as:
<syntaxhighlight lang="csharp">
Attributes
public ITemplate ContentTemplate { get; set; }
</syntaxhighlight>

===Collapsing comments===
Comments are a form of human-readable metadata, and lengthy comments can disrupt the flow of code. This can be the case either for a long comment for a short section of code, such as a paragraph to explain one line, or comments for [[documentation generator]]s, such as [[Javadoc]] or [http://msdn.microsoft.com/en-us/library/b2s063f7.aspx XML Documentation]. Code folding allows one to have long comments, but to display them only when required. In cases where a long comment has a single summary line, such as Python docstrings, the summary can still be displayed when the section is collapsed, allowing a summary/detailed view.

===Showing structure or sandwich code in structured programming===
[[Structured programming]] consists of nested blocks of code, and long blocks of code – such as long switch statements – can obscure the overall structure. Code folding allows one to see the overall structure and expand to a specific level. Further, in some uses, particularly strict structured programming (single function exit), there are code patterns that are hard to see when looking at expanded code. For example, in [[Resource management (computing)|resource management]] in structured programming, one generally acquires a resource, followed by a block of code using the resource, and finishing with releasing the resource. The acquisition/release pairing is hard to see if there is a long block of code in between, but easy to see if the intervening block is folded. Similarly, in conditional code like <code>if...then...else</code>, secondary blocks may be far from the condition statement.

===Grouping code===
Fold groups can be used to group code, either by explicit grouping – similar to comment blocks separating a module into sections, or class members into associated groups – or implicitly, such as by automatically grouping class members by access level.

===Hiding legacy code===
Legacy code – or any code that a developer does not wish to view or change at a given point in time – can be folded away so that programmers can concentrate on the code under consideration.

=== Hiding in-source data tables ===

==Conventions==
In order to support code folding, the text editor must provide a mechanism for identifying "folding points" within a text file. Some text editors provide this mechanism automatically, while others provide defaults that can either be overridden or augmented by the user.

There are various mechanisms, coarsely divided as automatic and manual – do they require any specification by the programmer? Folding points are usually determined with one or more of the following mechanisms. Each of these has its own distinct advantages and difficulties, and it is essentially up to the developers who create the text editor software to decide which to implement. Text editors that provide support for multiple folding mechanisms typically allow the user to choose which is most appropriate for the file being edited.

===Syntax-dependent===
Syntax-dependent folding points are those that rely on the content of the file being edited in order to specify where specific folding regions should begin and end. Syntax-based folding points are typically defined around any or all of the standard sub-features of the [[markup language]] or [[programming language]] in use. These are desirable due to being automatic and agreeing with code structure, but may require significant work to implement, and time to compute when editing a file.

===Indentation-based===
Indentation-based folding points are generally specified by the position and sequence of non-printing whitespace, such as tabs and spaces, within the text. This is most often used as a simple form of syntax-based folding, as indentation almost always reflects nesting level in [[indent style]]s for structured programming languages.

This convention is particularly suitable to syntaxes that have an [[off-side rule]], so the structure largely agrees with the indent. Examples include [[Python (programming language)|Python]] and text files that require indentation as a rule by themselves. However, even in these cases, structure does not exactly agree with indent, such as in [[line continuation]], and thus syntax-dependent folding is preferred.

===Token-based===
Token-based folding points are specified using special [[delimiter]]s that serve no other purpose in the text than to identify the boundaries of folding points. This convention can be compared to indentation-based folding points, where printable characters are used instead of whitespace. The most common delimiter tokens are <code>{{{</code> to begin the folded section, and <code>}}}</code> to end it.

Another notable token is <code>[http://msdn.microsoft.com/en-us/library/9a1ybwek.aspx #region]</code> ([http://msdn.microsoft.com/en-us/library/ed8yd1ha.aspx C# directives]), respectively <code>[http://msdn.microsoft.com/en-us/library/sd032a17.aspx #Region]</code> ([http://msdn.microsoft.com/en-us/library/7ah135z7.aspx Visual Basic directives]), used in [[Microsoft Visual Studio]] [[Microsoft Visual Studio#Code editor|Code Editor]]. These are treated syntactically as [[Directive (programming)|compiler directives]], though they do not affect compilation.

As a manual method, token-based folding allows discretion in grouping code based on arbitrary criteria, such as "functions related to a given task", which cannot be inferred from syntactic analysis.

Token-based folding requires in-band signalling, with folding tokens essentially being structured comments, and unlike other methods, are present in the source code and visible to other programmers. This allows them to be shared, but also requires their use (or preservation) by all programmers working on a particular file, and can cause friction and maintenance burden.

===User-specified===
User-specified folding allows the user to fold sections of text using a generic selection method, but without changing the source code (out-of-band), instead being specified only in the editor. For example, a programmer may select some lines of text and specify that they  should be folded. Folded text might be anonymous or named, and this may be preserved across editing sessions or discarded. Unlike token-based folding, this does not change the source text – it thus is not shared with other editors of the file, and is not visible in the code.

==Examples==
The following document contains folding tokens (<code><nowiki>{{{ ... }}}</nowiki></code>):

<pre><nowiki>
 Heading 1
 {{{
 Body
 }}}

 Heading 2
 {{{
 Body
 }}}

 Heading 3
 {{{
 Body
 }}}
</nowiki></pre>

When loaded into a folding editor, the outline structure will be shown:

<pre><nowiki>
 Heading 1
 {{{ ...

 Heading 2
 {{{ ...

 Heading 3
 {{{ ...
</nowiki></pre>

Usually clicking on the <code><nowiki>{{{</nowiki></code> marks makes the appropriate body text appear.

==Software with code folding capability==
One of the earliest folding editors was [[STET (text editor)|STET]], an editor written for the [[VM/CMS]] operating system in 1977 by [[Mike Cowlishaw]].  STET is a text editor (for documentation, programs, etc.) which folds files on the basis of blocks of lines; any block of lines can be folded and replaced by a name line (which in turn can be part of a block which itself can then be folded).

A folding editor appeared in the [[Occam programming language|occam]] [[Integrated development environment|IDE]] ''circa'' 1983, which was called the [[Inmos Transputer Development System (TDS)]]<ref>{{Cite book|title=Transputer research and applications, 2 : NATUG-2, proceedings of the Second Conference of the North American Transputer Users Group, October 18-19, 1989, Durham, NC|last=North American Transputer Users Group. Conference (2nd : 1989 : Durham, N.C.)|date=1990|publisher=IOS Press|others=Board, John A., Duke University.|isbn=9051990278|location=Amsterdam|pages=85|oclc=35478471}}</ref><sup>,</sup>.<ref>{{Cite web|url=http://www.transputer.net/tn/03/tn03.pdf|title=INMOS Technical Note 03 - Getting started with the TDS|last=Cormie|first=David|date=1986|website=transputer.net|access-date=2019-07-19}}</ref> The "f" editor (in list below) probably is the most intact legacy from this work.

The [[Apple Macintosh|Macintosh]] computer historically had a number of [[source code editor]]s that "folded" portions of code via "[[progressive disclosure|disclosure]] triangles".  The [[UserLand Software]] product Frontier is a scripting environment that has this capability.<ref>{{cite web|accessdate=2006-12-27|url=http://www.outliners.com/|title=Outliners.com|url-status=dead|archiveurl=https://web.archive.org/web/20061223230643/http://www.outliners.com/|archivedate=2006-12-23}}</ref><!-- This site doesn't actually verify this citation? -->

Folding is provided by many modern text editors, and [[#Conventions|syntax-based]] or semantics-based folding is now a component of many [[Integrated development environment|software development environments]]. Editors include:

<!-- (Please insert in alphabetical order) -->
{| class="wikitable sortable" style="text-align: center; width: auto; table-layout: fixed;"
|-
! style="width: 12em" | Name
! Token
! Indentation
! Syntax
! User
|-
| [[ABAP#ABAP_Workbench|ABAP Editor]]
| {{yes}}
| {{dunno}}
| {{yes}}
| {{dunno}}
|-
| AkelPad
| {{dunno}}
| {{dunno}}
| {{yes}}
| {{dunno}}
|-
| [[Anjuta|Anjuta IDE]]
| {{dunno}}
| {{yes}}
| {{yes}}
| {{dunno}}
|-
| [[Atom (text editor)|Atom]]{{efn|http://flight-manual.atom.io/using-atom/sections/folding/}}
| {{dunno}}
| {{yes}}
| {{dunno}}
| {{yes}}
|-
| [[BBEdit]]
| {{dunno}}
| {{dunno}}
| {{Yes}}
| {{dunno}}
|-
| [[Brackets (text editor)|Brackets]]
| {{yes2}}Plug-in
| {{yes}}
| {{yes}}
| {{no}}
|-
| [[Codeanywhere]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{dunno}}
|-
| [[Codenvy]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{dunno}}
|-
| [[Code::Blocks|Code::Blocks IDE]]
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
| [[Cubic IDE]]
| {{Yes}}
| {{Yes}}
| {{Yes}}
| {{Yes}}
|-
| CudaText
| {{dunno}}
| {{dunno}}
| {{dunno}}
| {{dunno}}

|-
| [[Delphi (IDE)|Delphi IDE]]
| {{Yes}}
| {{dunno}}
| {{Yes}}
| {{dunno}}
|-
| [[Adobe Dreamweaver|Dreamweaver]]
| {{dunno}}
| {{dunno}}
| {{dunno}}
| {{yes}}
|-
| [[Eclipse (software)|Eclipse]]
| {{dunno}}
| {{dunno}}
| {{yes}}
| {{dunno}}
|-
| EditPlus
| {{no}}
| {{yes}}
| {{no}}
| {{no}}
|-
| [[Emacs]]
| {{yes}}{{efn|Token-based folding is implemented by the [http://www.emacswiki.org/emacs/FoldingMode ''folding'' minor mode]. One can also use ''[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html outline]'' and ''[http://www.emacswiki.org/emacs/AllOut allout]'' minor modes for sectioning program sources.}}
| {{dunno}}{{efn|One can use the <code>set-selective-display</code> function in Emacs to hide lines based on the indentation level, as suggested in the [http://www.emacswiki.org/emacs/HideShow#toc4 Universal code folding] note.}}
| {{yes}}{{efn|1=Syntax-dependent folding is supported by the ''[https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html outline]'' and ''[http://www.emacswiki.org/emacs/AllOut allout]'' modes
for special dedicated [[Outline (list)|outline]]-syntaxes; by the ''[http://www.emacswiki.org/emacs/HideShow#toc3 hideshow]'' minor mode for some programming languages; also, by the ''[http://www.emacswiki.org/emacs/semantic-tag-folding.el semantic-tag-folding]'' minor mode and the <code>[http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/cedet/semantic/senator.el?h=cedet-branch#n484 senator-fold-tag]</code> command for [http://cedet.sourceforge.net/semantic.shtml syntaxes supported by ''semantic'' (a component of CEDET)], as well as by ''[http://www.emacswiki.org/emacs/DocMode doc-mode]'' for [[JavaDoc]] or [[Doxygen]] comments, by ''[https://www.gnu.org/software/auctex/manual/auctex/Folding.html#Folding TeX-fold-mode]'', <code>[http://www.lysator.liu.se/~lenst/about_psgml/psgml.html#Fold sgml-fold-element]</code> command, 
''[http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/nxml/nxml-outln.el?h=EMACS_23_1_RC#n23 nxml-outln]'' library in the corresponding language-specific modes, and possibly in other modes for particular syntaxes. Sometimes, the standard simple ''outline'' minor mode is used to simulate syntax-based folding, cf. the [http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/emacs-lisp/lisp-mode.el#n226 use] of it in properly indented Emacs Lisp source code, the [http://c2.com/cgi/wiki?EmacsOutlineMode use of it (see near the end of the page)] for properly indented HTML.  Several folding mechanisms are unified by the ''[http://www.emacswiki.org/emacs/FoldDwim fold-dwim]'' interface.  See also [http://www.emacswiki.org/emacs/CategoryHideStuff CategoryHideStuff].}}
| {{yes}}{{efn|Folding of user-selected regions in Emacs is implemented by the <code>[http://www.emacswiki.org/emacs/HideRegion hide-region-hide]</code> command.}}

|-
| [[EmEditor|EmEditor Professional]]
| {{dunno}}
| {{yes}}
| {{yes}}
| {{dunno}}

|-
| FlashDevelop IDE
| {{dunno}}
| {{dunno}}
| {{yes}}
| {{dunno}}

|-
| [[geany]]
| {{dunno}}
| {{yes}}
| {{yes}}
| {{dunno}}

|-
| [[gedit]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{dunno}}

|-
| [[ISPF#ISPF Editor|ISPF]]
| {{dunno}}
| {{Yes}}
| {{dunno}}
| {{Yes}}

|-
| [[JED (text editor)|JED]]
| {{yes}}
| {{yes}}{{efn|The <code>set_selective_display</code> function may be used to hide lines indented beyond a specified amount.}}
| {{dunno}}
| {{no}}

|-
| [[jEdit]]
| {{yes}}
| {{yes}} 
| {{yes}}
| {{yes}}

|-
| [[Kate (text editor)|Kate]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[MATLAB]]
| {{no}}
| {{no}}
| {{yes}}
| {{no}}

|-
| [[Microsoft Visual Studio|MS Visual Studio]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[NetBeans|NetBeans IDE]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[Notepad++]]
| {{dunno}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[PHPEd|NuSphere PHPEd]]
| {{dunno}}
| {{dunno}}
| {{Yes}}
| {{Yes}}

|-
| [[Qt Creator]]
| {{dunno}}
| {{dunno}}
| {{Yes}}
| {{dunno}}

|-
| [[SciTE]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{dunno}}

|-
| [[STET (text editor)|STET]]{{efn|STET may have been the first text editor that supported folding{{Citation needed|date=January 2008}}}}
| {{dunno}}
| {{dunno}}
| {{dunno}}
| {{dunno}}

|-
| [[TextMate]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[UltraEdit]]
| {{no}}
| {{no}}
| {{yes}}
| {{Yes}}

|-
| [[Vim (text editor)|Vim]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[Visual Expert]]
| {{dunno}}
| {{dunno}}
| {{yes}}
| {{dunno}}

|-
| [[Visual Studio Code]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{no}}

|-
| [[Xcode]]
| {{yes}}
| {{yes}}
| {{yes}}
| {{yes}}

|-
| [[Zend Studio]]
| {{dunno}}
| {{dunno}}
| {{dunno}}
| {{dunno}}
|}


===Other editors===
{{div col|colwidth=22em}}
* aoeui, the [[Dvorak Simplified Keyboard|Dvorak]]-optimized editor
* Author-it enterprise authoring and component content management software
* f (alias xf, Winf, Winf32)
* Folding Text Editor
* [[GFA BASIC]]
* GridinSoft Notepad
* [[IntelliJ IDEA]] (and other [[JetBrains]] IDEs)
* [[Keynote (notetaking software)|Keynote]]
* [[Komodo Edit]]
* [[Kwrite]]
* [[Leo (text editor)|Leo]]
* [[LEXX_(text_editor)|LEXX/LPEX]] (editor for the [[OED]])<ref>LEXX &ndash; A programmable structured editor ''IBM Journal of Research and Development'', Vol 31, No. 1, 1987, IBM Reprint order number G322-0151</ref>
* [[MonoDevelop]]
* [[NoteTab|NoteTab Pro]]
* [[Padre (software)|Padre]]
* RJ Text Editor
* [[Smultron]]
* [[The Hessling Editor]]
* [[Visual Studio]]
* [[WinShell]] (since version 3.30)
* [[XEDIT]] (however its folding is effected by scripts)
* Zeus
{{div col end}}

==See also==
*The [[Comparison of text editors#Programming features|Programming features]] section of the [[Comparison of text editors]] article for more editors that support folding
* [[Accordion (GUI)]], a similar UI technique applied to hierarchical lists rather than text

==Notes==
{{notelist}}

==References==
{{reflist}}
{{refbegin}}
* {{cite web|url=http://www.codinghorror.com/blog/2008/07/the-problem-with-code-folding.html |title=The Problem With Code Folding |first=Jeff |last=Atwood |authorlink=Jeff Atwood |work=Coding Horror |date=6 Jul 2008|postscript= – criticism of code folding, detailed comments on use.}}
{{refend}}

==External links==
{{Commons category}}
* [http://www.moria.de/~michael/fe/folding.html What is a folding editor?] by the author of the <code>[http://www.moria.de/~michael/fe/ fe]</code> editor.
* [http://www.wotug.org/occam/folding.shtml Description of the folding editor] used in [[occam (programming language)|occam]].
<!-- this next one already linked, above
* [http://hem.bredband.net/rj/TextEd/features.htm Explore the features] of the [http://hem.bredband.net/rj/TextEd/index.htm RJ TextEd] program.
-->

{{DEFAULTSORT:Code Folding}}
[[Category:Source code]]
[[Category:Text editor features]]
[[Category:Articles with example C Sharp code]]