This started with clicking a link in the IRC channel for yapc, which is all about Perl, but I don’t think the point is very language specific.
The link is Please Don’t Write Snowflake Code by Dave Rolsky, which, being from six years ago, isn’t meant (I don’t believe) to be a dig at kids today being sheltered, but for a coder developing preferences that isolate from the rest of the coding community.
Besides the prototype issue, none of these are wrong (and the prototype thing is arguably intended as documentation). The code works as written, and the meaning is more or less clear.
But it’s weird, because it’s not what most people other do. It’s a unique snowflake.
It’s a distraction.
Instead of looking at the code, experienced Perl programmers will spend time going “WTF” and wondering why this code looks different from all the other code they’ve seen.
I get that. When I look at and contribute to other people’s projects, I try to code to their conventions, and I do not have custom changes to the VS Code formatters for Javascript, CSS, HTML and whatever else I may have installed. SQL?
But I have 19 lines of perltidyrc, which gets pretty close to what I like to see:
--backup-and-modify-in-place
--block-brace-tightness=0
--brace-tightness=0
--closing-token-indentation=3
--continuation-indentation=4
--indent-block-comments
--indent-closing-brace
--indent-columns=4
--maximum-line-length=100
--no-outdent-long-quotes
--noopening-sub-brace-on-new-line
--opening-brace-always-on-right
--paren-tightness=0
--space-for-semicolon
--space-terminal-semicolon
--square-bracket-tightness=0
--stack-opening-tokens
--vertical-tightness-closing=0
--vertical-tightness=0
I started this from the .perltidyrc from Perl Best Practices, with the first change being verbose, because you are never going to remember what -cti=0 or -bt=1 mean after years of not changing your rc file.
But I developed my preferred indentation style well before I started with Perl, taking early C-as-subset-of-C++ courses as a CS undergraduate. It is pretty close to Ratliff style. Pulling from brute-force Sudoku code I wrote years ago, I tidied it with an empty config file and then with my preferred style.
# default style
use strict;
use warnings;
use feature qw{ say postderef signatures };
no warnings qw{ experimental::postderef experimental::signatures };
use subs qw{ solve_sudoku test_solution display_puzzle no_go_list };
use Data::Dumper;
my @array;
my @test;
my $x = 0;
my $debug = 0;
my $outcount = 0;
#READ IN DATA
while ( my $line = <DATA> ) {
chomp $line;
$line =~ s{\D}{ }mxg;
my @line = split m{|}mx, $line;
for my $y ( 0 .. 8 ) {
my $digit = ' ';
$digit = $line[$y] if defined $line[$y];
$array[$x][$y] = $digit;
}
$x++;
}
solve_sudoku( 0, 0, '' );
# my preferences
#!/usr/bin/perl
use strict ;
use warnings ;
use feature qw{ say postderef signatures } ;
no warnings qw{ experimental::postderef experimental::signatures } ;
use subs qw{ solve_sudoku test_solution display_puzzle no_go_list } ;
use Data::Dumper ;
my @array ;
my @test ;
my $x = 0 ;
my $debug = 0 ;
my $outcount = 0 ;
#READ IN DATA
while ( my $line = <DATA> ) {
chomp $line ;
$line =~ s{\D}{ }mxg ;
my @line = split m{|}mx, $line ;
for my $y ( 0 .. 8 ) {
my $digit = ' ' ;
$digit = $line[$y] if defined $line[$y] ;
$array[$x][$y] = $digit ;
}
$x++ ;
}
solve_sudoku( 0, 0, '' ) ;
The main differences I see are spaces (or lack of) after semicolons and whether the closing brackets are indented with the code they enclose or not. Oh yes, if the braces around array indexes are tight or not.
I’ve seen Stack Overflow people re-edit my code to something that won’t run because they so hated my indenting, which is in part why I don’t try to help there anymore. But I don’t believe these are too far into the fringe.
So, is this weird indenting that’s unreadable for anyone not Dave? Or am I fretting for nothing?
If you have any questions or comments, I would be glad to hear it. Ask me on Twitter or make an issue on my blog repo.
Top comments (17)
The indentation of the braces in the last code sample is very difficult for me to read. The ending braces to me appear to end a different block than they really do. I see the first ending brace as a stray and I think there is a missing brace when I look at the end. At a glance, statements appear to be in very different blocks than they really are.
The spacing before the semicolons looks "funny" to me since I see semicolons as a kind of coding punctuation and punctuation never has a space before it (at least in English), but the spacing is still perfectly legible and intelligible.
I see the braces going with the indented code, not the surrounding code. So, I would do this:
over
I started doing the
;thing so that, if I was copy-and-pasting a variable, I wouldn't also get the semicolon, but that's a carry-over from highlighting in a terminal window and paste-or-middle-button. It was the 1990s, and I don't think editors behave like that anymore.Wonder if your point about the closing braces is why the edited code on SO stopped working. Maybe someone really did get confused when editing and accidentally broke it.
I find the So moderators community one of the most toxic of all times, I tried posting twice and answering twice too, but there was always someone better than you to modify the contents as a way they please and bash you in the same way, I never tried again, too toxic in my experience
It's not a personal against you, it's documentation. It should follow the usual practices to be understood by any developer as fast as possible without having to take in consideration personal preferences like coding indentation and funny styling...
For .NET, questions modifications regarding style formatting follows the rules proposed by microsoft regarding code clarity and usual good practices to follow (stylecop). Should be the same for your case.
Yes I understand the reasons behind a good question, and why often questions are flagged as not appropriate, I like to receive feedback the bad thing is receiving feedback in a manner that looks like "I know better, and I know better what you want than you" while that might be the case it's just about communicating that instead of just exercising authority. And Also I know a pair of moderators shouldn't change my opinion of an entire community, but I'm not the only one nor the last that will have a similar opinion on the matter
I don't really understand why SO allows permission-less editing of folks' answers. The profile-driven UI combined makes it less-than-clear that certain work is not that of the original author.
Oh so true.
Hello Dave,
As a personal taste, i do find the second style braces to be harder to read than the first one, just like the others before me have stated. I find that it's easier to see a closing brace and the corresponding block of code if it's idented the same as the line on which the opening brace is. But still, after a few minutes of getting used to this, IF this identing style is consistent throughout your code, then i can adapt to it and have little to no problem reading your code. By the way, Python is such a language that forces this on us, as there are no opening/closing braces, so we have to look at identing to see blocks of code.
What i find to be suboptimal, if i may say so, and i see this on 99% of the source code written by other programmers, is not using naming conventions on variables & objects. For example, taking your above code, i would never ever write something like my $outcount = 0 ;, instead i would name that variable $nOutCount, so i can know imediately, when i look at it, that it's an integer variable (the n in front). Similarly, i wouldn't write my $line = <DATA>, but i would give it a name of $strLine, so i can clearly see it's a string variable. Same thing goes for every other data type. Yes, i know that in these kinds of languages, variables could change their type pretty easily, however i don't think anyone actually does this as it's verry confusing, so knowing what type of variable it is, without following the code, is a great benefit.
Cheers!
I’ve seen these attempts to make yourself comfortable in dynamically types languages, specifically PHP. I find them irritating at most, as you dont KNOW which type cariable will have at runtime (and if it will change it). So this prefixing gives you nothing but false-confidence. Is it somehow different in Python (does it infer type on init, but doesnt allow to change one, like Golang?)
Re: Your first paragraph
Similarly, when I'm dealing with other people's code, or maintaining things that are not exclusively mine, I am happy to work to that style. (Within parameters; I am refactoring a 2.5 KLOC program that not even the original developer felt comfortable fixing, and I am not respecting it's established style one bit.)
My problem is that the opening brace is not at the same line.
Wouldn't it be more like?
???
Unless you go full GNU-style...
Which makes it seem to me like sample_subroutine dropped the opening brace like Sonny dropped the gun in the restaurant scene in The Godfather.
My formatting is consistent, because of perltidy. I have a keystroke aliased in vim, and use the VS Code to allow Perl formatting (although I am convinced it is not using the installed perltidy executable, even though I have told it the path.)
My first degree is in Journalism, and many evenings doing full-page layout has given me a sensitivity to readability, but I don't want one person's view of readability forced upon me, especially when it can hide productivity bombs.
(First time I touched Python, in 2000 or so, it was indented with tabs, and someone -- maybe me, maybe the source, maybe a solar flare while in transit -- put a space before a tab, making the code non-functional and making my
hello worldexperience a couple hours of frantic debugging. I know this would not happen with Python 2.7 or 3.5, but it made me hate Python for 20 years. Now, I mostly hate Python packaging and how it routinely breaks my toys, but that's another matter.)On the subject of Force and One True Style, I was recently made aware that Go will reformat your code on compile, leading to swag that says GO FMT yourself.
I ... um ... yeah.
But thanks for the time you spent reading and responding. While I may not agree with your points, they are well-considered and well-expressed.
Re: Your second paragraph
That would be Hungarian Notation, correct?
I looked at it in the 1990s, hearing it was Microsoft house style, and decided that Perl kinda had this with the sigils; $, @, % and &. I get the point of it, but I didn't see it as adding value. I don't see anything gained by my $fpPi = 3.14159. because you know what Pi is and how it is used. (Incidentally, that could now be my $fpπ = 3.14159.)
The problem of "what kind of thing IS this variable" is lessened by not having code blocks larger than an editor window, so that you can see most everywhere $line is used.
This also gets to convention. Repeating the read:
@array is a two-dimensional array, and $x and $y represent positions within. $digit could be better-named, because it could be a single digit 1-9 but it could be a space, because I'm avoiding undefs. Is it better as $chDigit? But the whole thing is eleven lines and the only thing that is used after this is @array. (Which is too generic a name, but I couldn't think of a better one when I was coding it. @puzzle? @chPuzzle? @arrchPuzzle?
Currently, I'm doing a lot more with references, both arrayrefs and hashrefs, because I'm much more likely to pull from JSON or SQL, and the tools I have give me references, and I think that $objrefUser->{ uintID } would not give me any benefit.
There are places where it would make sense, but since I don't work in those places, I get why I am in the 99% on this one.
I could def survive in a codebase like that (I mean, hell, I can put up with the eslint nonsense). The closing curly braces are probably the hardest one for people b/c most people close blocks (I assume that's what they're called in Perl) at the level of the next line of code. Since we parse enough code that our brains eventually get competent at it without conscious focus, changing the indentation you close them makes it look (to most readers) like there's a bug. Ie my brain will subconsciously zero in on it, expecting to see a bug. But, that said, I'm sure I'd get used to it pretty quick and be fine. I've seen maybe 3 different brace styles in C and Java, and in the end was able to read all of them with minimal difficulty. So, no, I don't particularly have an issue with it (in your code, I'd probably reformat it if you sent it to me as a PR).
Personally most of the interactions I have on Stack Overflow are unhelpful and frustrating to the point that it's completely fallen out of use as an avenue for assistance. I think I went about 3 years without logging into it, until recently a lib requested questions be posted there instead of in issues.
SO: I go back and search, but between the attitude (👎) and the large body of answered questions (👍), I rarely ask new questions anymore.
Indent Styles: There are nine distinct styles in the "Indentation Style" Wikipedia page. I suspect that, until we can generate and compile flowcharts, or can explain the problem and have Alexa code it for us, how we handle braces will be a bone of contention.
And, esp. if your repo had a perltidyrc in it, as some do, I'd try to conform to your style before sending.
You are right, it's YOUR preferred style ;)
The second paragraph is very hard to read, for most types of developers with knowledge of most types of langauges, and fixing it to the first is a must..
I could accept harder, although I don't see it. I do not understand very hard, and would like to know why.
I hear a similarly dogmatic cry that dark-text-on-light-backgrounds being very hard to read, while my astigmatism makes it far easier to read, because blurriness. (Eye exam and new lenses next week, so it is fixable.)
And I might comment that I find langauges very hard to read...