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?
I noticed that for a lot of the files I make, the documentation and comments are a good percentage of the bulk.
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ā¦ ?
With emacs, I find outline-minor-mode very convenient, for even longer files.
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.
Good stuff, but do you use Documenter.jl to document your Julia packages? I didnāt know there was another way to include docstringsā¦
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!).
"""
your doc here
"""
object_name
Where can I find analysejuliafiles?
1 Like
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.
That makes me very happy Iāll never have to do āthe whole MATLABā thing 
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?
No blank lines in your code? Yikes. Do you also prefer books without paragraphs?
no unnecessary empty lines. when in doubt, donāt use
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.
Very easily:
"""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
arenāt you assuming too much?
and there is something i have said that contradicts that?
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)
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.
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!