Adding file length as constraint to style guide

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 :wink:

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? :wink:

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!