Inconsistent use of underscores in attribute names #4228

knuesel · 2023-01-05T12:25:41Z

knuesel
Jan 5, 2023

streamplot has attributes arrow_head and arrow_size while arrows has the same without underscore. Looking at the different plotting functions, it appears that the vast majority of attributes has no underscore, so it would make sense to rename the streamplot attributes?

More generally, it might improve usability to have all attributes without underscores, maybe with some well thought exceptions?

Of course removing underscores reduces the readability of the attribute, but I think in most cases, having a uniform API gives a gain in usability that outweighs the loss in readability.

The following bash script (run from the Makie.jl directory) tries to find all the attributes with underscores:

regex='^\s*[a-z]*\(_[a-z]*\)\+\s*=.*,\(\s*#.*\)\?$'
files=($(grep -l "$regex" $(grep -l --exclude=helpers.jl '\(Attributes\|Theme\)(;\?$' -r src MakieCore)))
for i in "${files[@]}"; do
    echo "$i:"
    grep "$regex" "$i" | cut -d= -f1 | awk '{print "\t", $1}' | sort | uniq
done

Here are the results (probably with some false positives and some results missing):

Attributes with underscores (click to expand)

src/makielayout/defaultattributes.jl:
	 flip_vertical_label
src/interaction/inspector.jl:
	 _color
	 enable_indicators
	 indicator_color
	 indicator_linestyle
	 indicator_linewidth
	 indicator_visible
src/camera/old_camera3d.jl:
	 pan_button
	 rotate_button
src/camera/camera3d.jl:
	 backward_key
	 circular_rotation
	 contract_view_key
	 down_key
	 fixed_axis
	 fix_x_key
	 fix_y_key
	 fix_z_key
	 forward_key
	 keyboard_rotationspeed
	 keyboard_translationspeed
	 keyboard_zoomspeed
	 left_key
	 mouse_rotationspeed
	 mouse_translationspeed
	 mouse_zoomspeed
	 pan_left_key
	 pan_right_key
	 right_key
	 roll_clockwise_key
	 roll_counterclockwise_key
	 rotation_button
	 rotation_center
	 scroll_mod
	 stretch_view_key
	 tilt_down_key
	 tilt_up_key
	 translation_button
	 update_rate
	 up_key
	 zoom_in_key
	 zoom_out_key
	 zoom_shift_lookat
src/camera/camera2d.jl:
	 last_area
	 update_limits
src/basic_recipes/axis.jl:
	 k_ideal
	 k_max
	 k_min
	 ranges_labels
	 strict_span
src/basic_recipes/series.jl:
	 solid_color
src/basic_recipes/contours.jl:
	 enable_depth
src/basic_recipes/tooltip.jl:
	 depth_shift
	 outline_color
	 outline_linestyle
	 outline_linewidth
	 triangle_size
src/basic_recipes/barplot.jl:
	 bar_labels
	 color_over_background
	 color_over_bar
	 dodge_gap
	 flip_labels_at
	 label_args
	 label_color
	 label_font
	 label_formatter
	 label_offset
	 label_rotation
	 label_size
	 nan_color
	 n_dodge
src/basic_recipes/poly.jl:
	 nan_color
src/basic_recipes/pie.jl:
	 inner_radius
	 vertex_per_deg
src/basic_recipes/streamplot.jl:
	 arrow_head
	 arrow_size
src/basic_recipes/volumeslices.jl:
	 bbox_visible
src/basic_recipes/tricontourf.jl:
	 computed_colormap
	 nan_color
src/basic_recipes/waterfall.jl:
	 direction_color
	 dodge_gap
	 final_color
	 final_dodge_gap
	 final_gap
	 marker_neg
	 marker_pos
	 n_dodge
	 show_direction
	 show_final
src/basic_recipes/contourf.jl:
	 computed_colormap
	 nan_color
src/theming.jl:
	 axis_type
	 figure_padding
	 focus_on_show
	 pause_renderloop
	 pt_per_unit
	 px_per_unit
	 render_on_demand
src/interfaces.jl:
	 depth_shift
	 nan_color
src/stats/boxplot.jl:
	 dodge_gap
	 n_dodge
	 outlier_indices
	 show_median
	 show_midline
	 show_notch
	 show_outliers
	 t_segments
src/stats/crossbar.jl:
	 dodge_gap
	 n_dodge
	 show_midline
	 show_notch
src/stats/hist.jl:
	 bar_labels
	 flip_labels_at
	 label_color
	 label_font
	 label_offset
	 label_size
	 over_background_color
	 over_bar_color
	 scale_to
src/stats/violin.jl:
	 dodge_gap
	 max_density
	 n_dodge
	 show_median
MakieCore/src/basic_plots.jl:
	 depth_shift
	 invert_normals
	 marker_offset
	 nan_color
	 transform_marker
	 uv_offset_width
	 word_wrap_width

Some possibilities:

Remove all underscores
Put underscores everywhere
Remove all underscores, except for cameras (put underscores everywhere there)

What do you think?

ffreyer · 2023-01-07T13:58:54Z

ffreyer
Jan 7, 2023
Maintainer

I agree that something like arrow_size and arrowsize shouldn't coexist. I'm not sure if I agree with having underscores everywhere or nowhere. I think there are some cases where underscores help readability and others where it's better without. That being said I also find myself wondering sometimes whether there is an underscore in an attribute name or not. Maybe we could keep it to a select few prefixes without underscore (like is, has, min, max, single characters) and use underscores consistently otherwise?

The Julia style guide also suggests having no underscores for simple names. Though that is rather subjective...

functions are lowercase (maximum, convert) and, when readable, with multiple words squashed together (isequal, haskey). When necessary, use underscores as word separators. Underscores are also used to indicate a combination of concepts (remotecall_fetch as a more efficient implementation of fetch(remotecall(...))) or as modifiers.

0 replies

jkrumbiegel · 2023-01-07T16:29:55Z

jkrumbiegel
Jan 7, 2023
Maintainer

I think we followed that rule that underscores come in only when they are needed for readability. What could help additionally would be erroring on nonexistent keyword attributes and giving suggestions. Then one could quickly find misspelled variants.

0 replies

knuesel · 2023-01-09T16:12:02Z

knuesel
Jan 9, 2023
Author

I think we followed that rule that underscores come in only when they are needed for readability.

Right but I'm not sure it works in practice because "needed for readability" is so subjective. So now the result is that it's difficult to guess when there should be an underscore. Who would guess that patchstrokecolor needs no underscore but nan_color does? Or roundedrectpoints vs t_segments, or notchmin vs k_min?

It would be great to make this more predictable.

Maybe we could keep it to a select few prefixes without underscore (like is, has, min, max, single characters) and use underscores consistently otherwise?

Yes I think something in this direction is a good idea: identify some "grammar" rules that work well. Looking at the existing keywords, it seems that underscores are most often used in the following cases:

Around verbs and prepositions
To separate plot elements from other-level things such as "mouse" and "key".

I think both rules make a lot of sense:

The first rule is often required to make things readable: the least readable keywords are often due to mixing nouns with verbs and prepositions without delimiters. For example fliplabelsat reads much worse than the current flip_labels_at.
The second rule is quite intuitive (more strongly separating things that are on a different level). It's also consistent with the style guide quoted by @jkrumbiegel (_ to indicate a "combination of concepts").

0 replies

knuesel · 2023-01-09T16:23:28Z

knuesel
Jan 9, 2023
Author

Let's see what happens if we apply the suggested rules: use underscores systematically around verbs and prepositions and other-level things (like "mouse"), and never otherwise.

Click to expand the list at the bottom to see all the Makie keywords (probably not an exact list) with

the result of the rules in the left column,
the original keyword in the right column (empty when the original already agrees with the rules).

I think the suggested list really makes things more consistent and predictable without hurting readability. In a couple of cases it would make things worse, but then it can make sense to further change the keyword:

k_ideal should become kideal, maybe a bit odd but we could use kbest instead.
For marker_neg, marker_pos I propose markernegative and markerpositive (it also removes the ambiguity that "pos" could mean "position").
For ranges_labels maybe use ranges_and_labels.

Note: I removed over_background_color and over_bar_color which are listed in hist.jl but look like bugs (it should be color_over_background and color_over_bar as in barplot.jl).

Suggested vs original keywords (click to expand)

Suggested	Original (when different)
`algorithm`
`align`
`alpha`
`ambient`
`antialias`
`area`
`args`
`arrowhead`	`arrowhead` and `arrow_head`
`arrowsize`	`arrowsize` and `arrow_size`
`arrowtail`
`axis`
`axiscolor`
`axislinewidth`
`axisnames`
`axistype`	`axis_type`
`backgroundcolor`
`backlight`
`backward_key`
`bandwidth`
`barlabels`	`bar_labels`
`bars`
`bboxvisible`	`bbox_visible`
`bgcolor`
`bias`
`bins`
`blur`
`bottomspinecolor`
`bottomspinevisible`
`boundary`
`boxcolor`
`boxmax`
`boxmin`
`boxwidth`
`cad`
`camera`
`cellsize`
`centers`
`circularrotation`	`circular_rotation`
`colgap`
`color`	`color` and `_color`
`colormap`
`color_over_background`
`color_over_bar`
`colorrange`
`computedcolormap`	`computed_colormap`
`contract_view_key`
`cornerradius`
`cornersegments`
`cycle`
`datalimits`
`debugging`
`decorated`
`density`
`depth`
`depthshift`	`depth_shift`
`diffuse`
`direction`
`directioncolor`	`direction_color`
`distancefield`
`dodge`
`dodgegap`	`dodge_gap`
`down_key`
`enabled`
`enable_depth`
`enable_indicators`
`endpoints`
`extend_high`	`extendhigh`
`extend_low`	`extendlow`
`eyeposition`
`far`
`figurepadding`	`figure_padding`
`fill_to`	`fillto`
`finalcolor`	`final_color`
`finaldodgegap`	`final_dodge_gap`
`finalgap`	`final_gap`
`fixedaxis`	`fixed_axis`
`fix_x_key`
`fix_y_key`
`fix_z_key`
`flip_labels_at`
`flipped`
`flip_verticallabel`	`flip_vertical_label`
`float`
`focus_on_show`
`font`
`fonts`
`fontsize`
`formatter`
`forward_key`
`fov`
`framecolor`
`framerate`
`framesize`
`framevisible`
`fullscreen`
`fxaa`
`gap`
`glowcolor`
`glowwidth`
`gridsize`
`highclip`
`indicatorcolor`	`indicator_color`
`indicatorlinestyle`	`indicator_linestyle`
`indicatorlinewidth`	`indicator_linewidth`
`indicatorvisible`	`indicator_visible`
`innerradius`	`inner_radius`
`inspectable`
`interpolate`
`invert_normals`
`isorange`
`isovalue`
`iterations`
`justification`
`keyboard_rotationspeed`
`keyboard_translationspeed`
`keyboard_zoomspeed`
`kbest`	`k_ideal`
`kmax`	`k_max`
`kmin`	`k_min`
`l`
`label`
`labelcolor`	`label_color` and `labelcolor`
`labelfont`	`label_font`
`labelformatter`	`label_formatter`
`labeloffset`	`label_offset`
`labelpadding`
`labelrotation`	`label_rotation`
`labels`
`labelsize`	`label_size` and `labelsize`
`labelvisible`
`lastarea`	`last_area`
`left_key`
`leftspinecolor`
`leftspinevisible`
`legend`
`lengthscale`
`levels`
`lightposition`
`limits`
`linebuffer`
`linecolor`
`lineheight`
`linestyle`
`linewidth`
`look_at`	`lookat`
`lowclip`
`lowerupper`
`marker`
`markercolor`
`markercolormap`
`markercolorrange`
`markernegative`	`marker_neg`
`markeroffset`	`marker_offset`
`markerpositive`	`marker_pos`
`markersize`
`markerspace`
`markerstrokecolor`
`markerstrokewidth`
`maxdensity`	`max_density`
`maxsteps`
`mediancolor`
`medianlinewidth`
`medians`
`midlinecolor`
`midlinewidth`
`minortickalign`
`minortickcolor`
`minorticks`
`minorticksize`
`minorticksvisible`
`minortickwidth`
`mode`
`model`
`monitor`
`mouse_rotationspeed`
`mouse_translationspeed`
`mouse_zoomspeed`
`nancolor`	`nan_color`
`ndodge`	`n_dodge`
`near`
`normalization`
`normalize`
`notchmax`
`notchmin`
`notchwidth`
`npoints`
`offset`
`oit`
`orientation`
`outliercolor`
`outlierindices`	`outlier_indices`
`outliers`
`outlierstrokecolor`
`outlierstrokewidth`
`outlinecolor`	`outline_color`
`outlinelinestyle`	`outline_linestyle`
`outlinelinewidth`	`outline_linewidth`
`overdraw`
`padding`
`palette`
`pan_button`	`pan_button` and `panbutton`
`pan_left_key`
`pan_right_key`
`patchcolor`
`patchstrokecolor`
`patchstrokewidth`
`pause_renderloop`
`placement`
`plugin`
`points`
`position`
`projectiontype`
`pt_per_unit`
`px_per_unit`
`quality`
`radius`
`range`
`ranges_and_labels`	`ranges_labels`
`rect`
`renderloop`
`render_on_demand`
`reset`
`resolution`
`resource`
`reversed`
`right_key`
`rightspinecolor`
`rightspinevisible`
`roll_clockwise_key`
`roll_counterclockwise_key`
`rotate_button`
`rotation`
`rotation_button`
`rotationcenter`	`rotation_center`
`rotations`
`rotationspeed`
`roundedrectpoints`
`rowgap`
`scale`
`scale_to`
`scroll_mod`
`selection_button`	`selectionbutton`
`shading`
`shininess`
`show_axis`	`showaxis`
`show_direction`
`show_final`
`show_grid`	`showgrid`
`show_median`
`show_midline`
`show_notch`
`show_outliers`
`show_ticks`	`showticks`
`side`
`solidcolor`	`solid_color`
`space`
`specular`
`spinecolor`
`spinewidth`
`ssao`
`stack`
`stemcolor`
`stemcolormap`
`stemcolorrange`
`stemlinestyle`
`stemwidth`
`step`
`stepsize`
`stretch_view_key`
`strictspan`	`strict_span`
`strokearound`
`strokecolor`
`strokewidth`
`textbuffer`
`textcolor`
`textpadding`
`threshold`
`tickalign`
`tickcolor`
`tickformat`
`ticklabelalign`
`ticklabelcolor`
`ticklabelpad`
`ticklabelrotation`
`ticklabelsize`
`ticklabelspace`
`ticklabelsvisible`
`ticks`
`ticksize`
`ticksvisible`
`tickwidth`
`tilt_down_key`
`tilt_up_key`
`title`
`topspinecolor`
`topspinevisible`
`transformation`
`transform_marker`
`translation_button`
`translationspeed`
`transparency`
`trianglesize`	`triangle_size`
`trim_spine`	`trimspine`
`trunkcolor`
`trunkcolormap`
`trunkcolorrange`
`trunklinestyle`
`trunkwidth`
`tsegments`	`t_segments`
`update_limits`
`updaterate`	`update_rate`
`up_key`
`upvector`
`uvoffsetwidth`	`uv_offset_width`
`vertex_per_deg`
`visible`
`vsync`
`weights`
`whiskercolor`
`whiskerlinewidth`
`whiskers`
`whiskerwidth`
`width`
`wordwrapwidth`	`word_wrap_width`
`xautolimits`
`xgridcolor`
`xgridvisible`
`xgridwidth`
`xlabelpadding`
`xmax`
`xmin`
`xminorgridcolor`
`xminorgridvisible`
`xminorticksvisible`
`xspinesvisible`
`xtickcolor`
`xticklabelcolor`
`xticklabelpad`
`xticksize`
`xticksvisible`
`xtickwidth`
`xypanelcolor`
`xypanelvisible`
`xzpanelcolor`
`xzpanelvisible`
`yautolimits`
`ygridcolor`
`ygridvisible`
`ygridwidth`
`ymax`
`ymin`
`yminorgridcolor`
`yminorgridvisible`
`yminorticksvisible`
`yspinesvisible`
`ytickcolor`
`yticklabelcolor`
`yticklabelpad`
`yticksize`
`yticksvisible`
`ytickwidth`
`yzpanelcolor`
`yzpanelvisible`
`zautolimits`
`zgridcolor`
`zgridvisible`
`zoom_button`	`zoombutton`
`zoom_in_key`
`zoom_out_key`
`zoom_shift_look_at`	`zoom_shift_look_at`
`zoomspeed`
`zspinesvisible`
`ztickcolor`
`zticklabelcolor`
`zticklabelpad`
`zticksvisible`

What do you think?

0 replies

maxfreu · 2024-08-21T23:45:30Z

maxfreu
Aug 21, 2024

This just tripped me up as well. Furthermore it seems, that e.g. for Legend no keyword checks are in place. So having label_font like in Figure just changes nothing...

0 replies

ffreyer · 2024-08-24T14:08:09Z

ffreyer
Aug 24, 2024
Maintainer

Related: #2519, #2520

0 replies

maxfreu · 2024-08-29T19:33:37Z

maxfreu
Aug 29, 2024

Ok, since this has been converted to a discussion, let's discuss. I like the proposed changes and have only four points: 1) Keep flip_vertical_label as is or remove all underscores, flip_verticallabel looks odd to me. 2) Keep selectionbutton. 3) Remove underscores for show*. 4) One might consider outlinestyle and outlinewidth instead of the double outlineline*.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Inconsistent use of underscores in attribute names #4228

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 7 comments

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

Inconsistent use of underscores in attribute names #4228

knuesel Jan 5, 2023

Replies: 7 comments

ffreyer Jan 7, 2023 Maintainer

jkrumbiegel Jan 7, 2023 Maintainer

knuesel Jan 9, 2023 Author

knuesel Jan 9, 2023 Author

maxfreu Aug 21, 2024

ffreyer Aug 24, 2024 Maintainer

maxfreu Aug 29, 2024

knuesel
Jan 5, 2023

ffreyer
Jan 7, 2023
Maintainer

jkrumbiegel
Jan 7, 2023
Maintainer

knuesel
Jan 9, 2023
Author

knuesel
Jan 9, 2023
Author

maxfreu
Aug 21, 2024

ffreyer
Aug 24, 2024
Maintainer

maxfreu
Aug 29, 2024