# Adding file length as constraint to style guide

**URL:** <https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005>\
**Category:** Internals & Design\
**Created:** [February 9, 2017, 7:22pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005 "2017-02-09T19:22:07Z")\
**Posts on this page:** 16\
**Page:** 2

<div class="post-metadata">

**Author:** ![DNF](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dnf/32/10191_2.png) [@DNF](https://discourse.julialang.org/u/DNF)\
**Post date:** [February 10, 2017, 8:35am UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/21 "2017-02-10T08:35:53Z")

</div>

> [@stst](#):
>
> From a user experience perspective, an ideal IDE or editor lets you navigate between functions easily, no matter whether they are in the same file or in another file. Functions are the natural logical and navigational units. Files are irrelevant.

Not sure I fully agree. Splitting definitions that are strongly related into different files, makes it harder to view them next to each other, and may confuse the bigger picture. Or are you saying that an IDE help you see which definitions belong together, even when they are split into different files? If so, which IDE are you using?

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [February 10, 2017, 1:46pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/22 "2017-02-10T13:46:38Z")

</div>

I noticed that for a lot of the files I make, the documentation and comments are a good percentage of the bulk.

```nohighlight
julia> analysejuliafiles("Luxor/src")
      2086 source lines       
       186 comment lines      
      1753 documentation lines
       315 source lines were blank
        95 lines were longer than 92 characters
         in 15 files
Filename #source lines	#comments #Docs #empty source	> 92        	
Luxor/src/Luxor.jl 349 9 360 72 20          	
Luxor/src/Turtle.jl 128 6 90 19 0           	
Luxor/src/animate.jl 32 3 37 2 9           	
Luxor/src/arrows.jl 71 13 27 3 6           	
Luxor/src/blends.jl 62 1 113 13 2           	
Luxor/src/colors_styles.jl 93 10 125 15 13          	
Luxor/src/curves.jl 202 23 234 27 11          	
Luxor/src/images.jl 22 1 33 5 1           	
Luxor/src/juliagraphics.jl 172 15 26 19 1           	
Luxor/src/matrix.jl 79 8 142 16 1           	
Luxor/src/point.jl 211 19 141 41 7           	
Luxor/src/polygons.jl 359 52 139 36 9           	
Luxor/src/shapes.jl 78 0 85 11 4           	
Luxor/src/text.jl 140 18 154 29 6           	
Luxor/src/tiles-grids.jl 88 8 47 7 5           	

```

It’s much easier to keep the documentation and source code next to each other.

I don’t have a problem with files that are up to 1000 lines long. Perhaps it depends on the editor… ?

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [February 10, 2017, 1:57pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/23 "2017-02-10T13:57:23Z")

</div>

> [@cormullion](#):
>
> Perhaps it depends on the editor… ?

With `emacs`, I find `outline-minor-mode` very convenient, for even longer files.

---

<div class="post-metadata">

**Author:** ![pint](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pint/32/125_2.png) [@pint](https://discourse.julialang.org/u/pint)\
**Post date:** [February 10, 2017, 2:08pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/24 "2017-02-10T14:08:05Z")

</div>

i wonder if i’m alone with this, but i hate documentation being interspersed with code. i put them in a different file instead. i also like to put boring bookkeeping stuff in different files. like, adding indexing interface to your type if it is not essential. or providing arithmetic operations and conversions. into a file they go. that keeps the main file lean and on point.

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [February 10, 2017, 2:24pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/25 "2017-02-10T14:24:38Z")

</div>

Good stuff, but do you use Documenter.jl to document your Julia packages? I didn’t know there was another way to include docstrings…

---

<div class="post-metadata">

**Author:** ![pint](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pint/32/125_2.png) [@pint](https://discourse.julialang.org/u/pint)\
**Post date:** [February 10, 2017, 2:36pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/26 "2017-02-10T14:36:01Z")

</div>

the syntax is the following, and it can be anywhere after the thing is defined. you can even use a comma sep list of objects, and the doc string will be associated with all of them (nice for pairs of functions like `thing` and `thing!`).

```julia
"""
your doc here
"""
object_name

```

---

<div class="post-metadata">

**Author:** ![josefsachs](https://avatars.discourse-cdn.com/v4/letter/j/f475e1/32.png) [@josefsachs](https://discourse.julialang.org/u/josefsachs)\
**Post date:** [February 10, 2017, 2:43pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/27 "2017-02-10T14:43:34Z")

</div>

> [@cormullion](#):
>
> analysejuliafiles

Where can I find `analysejuliafiles`?

---

<div class="post-metadata">

**Author:** ![ScottPJones](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/scottpjones/32/146_2.png) [@ScottPJones](https://discourse.julialang.org/u/ScottPJones)\
**Post date:** [February 10, 2017, 4:47pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/28 "2017-02-10T16:47:23Z")

</div>

I very much prefer to have the documentation to be right next to the code.  
Too frequently I’ve seen documentation get horribly out of sync when it’s documented elsewhere,  
and it’s a pain to have to go editing multiple files instead of just one, if I add a parameter, etc. to a function.  
These days, with nice packages that can extract the documentation from the code, I can’t see any reason to do otherwise.

---

<div class="post-metadata">

**Author:** ![ScottPJones](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/scottpjones/32/146_2.png) [@ScottPJones](https://discourse.julialang.org/u/ScottPJones)\
**Post date:** [February 10, 2017, 4:48pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/29 "2017-02-10T16:48:55Z")

</div>

That makes me very happy I’ll never have to do “the whole MATLAB” thing 😉

---

<div class="post-metadata">

**Author:** ![pint](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pint/32/125_2.png) [@pint](https://discourse.julialang.org/u/pint)\
**Post date:** [February 10, 2017, 5:34pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/30 "2017-02-10T17:34:32Z")

</div>

i like to write dense code in order to 1, see more stuff at once, and 2, navigate easily. so i don’t like unnecessary empty lines either, nor full-row comments, but especially documentation. in hell, i will use c++ with single braces occupying entire rows.

how do you provide common doc for multiple functions? most notably the inplace / allocating versions? and where do you put the documentation of a function that has many methods, and you don’t want to document each method?

---

<div class="post-metadata">

**Author:** ![DNF](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dnf/32/10191_2.png) [@DNF](https://discourse.julialang.org/u/DNF)\
**Post date:** [February 10, 2017, 7:01pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/31 "2017-02-10T19:01:40Z")

</div>

No blank lines in your code? Yikes. Do you also prefer books without paragraphs? 😉

---

<div class="post-metadata">

**Author:** ![pint](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pint/32/125_2.png) [@pint](https://discourse.julialang.org/u/pint)\
**Post date:** [February 10, 2017, 7:15pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/32 "2017-02-10T19:15:07Z")

</div>

no _unnecessary_ empty lines. when in doubt, don’t use

---

<div class="post-metadata">

**Author:** ![ScottPJones](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/scottpjones/32/146_2.png) [@ScottPJones](https://discourse.julialang.org/u/ScottPJones)\
**Post date:** [February 10, 2017, 7:34pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/33 "2017-02-10T19:34:44Z")

</div>

> [@pint](#):
>
> i like to write dense code in order to 1, see more stuff at once, and 2, navigate easily. so i don’t like unnecessary empty lines either, nor full-row comments, but especially documentation. in hell, i will use c++ with single braces occupying entire rows.

That reminds me of a programmer at my former job, who liked to fill his 80x25 editor windows with as much text as possible - one character variable names, loops all on one line, no comments. Absolutely _nobody_ wanted to deal with his code! I don’t believe in going overboard, I’ll use short forms like one-line function definitions or conditional statements with `&&` and `||`, but my experience (dating from my days of MacLisp & Scheme) is that whitespace and indentation can be critical tools to making code readable.

> [@pint](#):
>
> how do you provide common doc for multiple functions?

Very easily:

```julia
"""My doc string"""
function myfunction end

# this is my specialized method for AbstractStrings
function myfunction(foo::AbstractString) ... end
# this is my specialized method for Vector{UInt8}
function myfunction(foo::Vector{UInt8}) ... end

```

---

<div class="post-metadata">

**Author:** ![pint](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pint/32/125_2.png) [@pint](https://discourse.julialang.org/u/pint)\
**Post date:** [February 10, 2017, 9:43pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/34 "2017-02-10T21:43:51Z")

</div>

> [@ScottPJones](#):
>
> That reminds me of a programmer

aren’t you assuming too much?

> [@ScottPJones](#):
>
> is that whitespace and indentation can be critical

and there is something i have said that contradicts that?

---

<div class="post-metadata">

**Author:** ![ScottPJones](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/scottpjones/32/146_2.png) [@ScottPJones](https://discourse.julialang.org/u/ScottPJones)\
**Post date:** [February 11, 2017, 12:01am UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/35 "2017-02-11T00:01:51Z")

</div>

> [@pint](#):
>
> aren’t you assuming too much?

I was just describing one very extreme example of a person’s rationale for packing as much as he could on one screen, not you! My point being more that I think one needs to try to find a balance between no in-line documentation, no descriptive variables, things packed onto single lines as much as possible, and too much whitespace, comments that basically repeat what the code is doing without adding information (instead of describing the API, and any “tricks” that might not be immediately obvious)

> [@pint](#):
>
> and there is something i have said that contradicts that?

No, was just remembering that particular developer, and meetings and wasted time trying to figure out just what in the world his code was really doing.

---

<div class="post-metadata">

**Author:** ![js135005](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/js135005/32/8219_2.png) [@js135005](https://discourse.julialang.org/u/js135005)\
**Post date:** [September 9, 2018, 2:24pm UTC](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005/37 "2018-09-09T14:24:33Z")

</div>

Sounds like the old APL (and more recently Perl) game of writing the most obscure code that fits in one line and inviting people to guess what it does.

On the current topic, there are many valid coding styles - the important things is that code is best if it is concise, efficient, and understandable. However some algorithms are not that easy to understand. Documentation to the rescue!

[Previous page](https://discourse.julialang.org/t/adding-file-length-as-constraint-to-style-guide/2005.md?page=1)