Steven HoeferCode should not be self documenting because code only knows its function, not it's purpose.
Code should be written so its function is clear. Comments and documentation should make its purpose and existence clear.
jimfl@troublewithwords Documentation: why this module consists of 35 definitions of a function called `traverse()`
Bytebro 🇬🇧 🇺🇦 🇬🇱When I started out cutting code in 1978, I thought 'elegant' was important. Once I started working on other people's code I realised that 'clear' always trumps 'elegant'.
Orb 2069Nothing like watching five years of people maintaining your 'elegant' code with a hammer and a fist full of 'if' statement to clarify that you should have been more explicit.
True. I've mentioned here before, but one of my favourite ever comment blocks I found in 15yr old legacy code basically said
"If you don't understand this next block of code, *please* don't change it. It took a long time to get it working as it should!"
Of COURSE there weren't any comments helping said viewer understand the code?
My guess is that the original person thought 'anyone bright enough to understand this code, will understand the comment'. No idea - it was a while ago.
Jyrgen N@bytebro @troublewithwords elegant is
[$a => $b] -> [$a <= $b]
Clear is
a if a > b else b
(sorry, @simoncozens)
mirabilos🐈⬛@jyrgenn @troublewithwords @simoncozens @bytebro my brain reads that as (a if a) > (b else b)
Python3 is not clear. It’s emulating one of the less clear parts of Perl here.
The older and…or (if its pitfall doesn’t apply) is clearer. Or, if needs must, the Ansible-Jinja ternary filter.
Clearest is the C ternary operator with parenthesēs if a term is more than a word.
I know nothing of Python even though I have the allegedly definitive reference book right here on my shelf next to my copy of _Programming Perl_! 🙂
Perl is 'clear', within its limits. I may be wrong but I think even Larry Wall might have said as much.
If you absolutely have to prioritise 'safety' over clarity, then yeah, you probably ought to be writing Rust or something, but that's not my background at all.
Absolutely. Or the old one about zeroing a thing by XORing it with itself. In assembly language, absolutely - knock yourself out, everybody does that.
But in a higher level language? Don't do that, mainly bcs the compiler will work that out anyway, and you are obfuscating the important stuff which is 'the code'.
sarah tonin 
@troublewithwords when it comes to libraries, interfaces and implementations should be separated for this exact reason. the documentation in interfaces contain the information of what is available and how to use it, the documentation in implementations explain how it works
@troublewithwords when i'm hacking with a library, i don't care how it's implemented exactly, but when i'm hacking ON a library, i very much do
Alex is Adjusting@troublewithwords as a technical writer, I don't think this is a controversial opinion at all
éric 🚲 🇪🇺 
@troublewithwords
Code is *how* and comments are *why*. At least, this is what I tell my students.
Code is *how* and comments are *why*. At least, this is what I tell my students.
Hazelnoot@ericsfraga @troublewithwords I like to use a variant of this:
- code is how
- architecture is what
- comments are why
- code is how
- architecture is what
- comments are why
Jack William BellI have a whole rant about how every CLI app needs a new option. Like ‘-help’ (or ‘-h’ or ‘-?’) which tells you *what*, except it's ‘-e’ or ‘-explain’ and it tells you *why* and *for what*.
@jackwilliambell This is so good!
Andrew@jackwilliambell @troublewithwords oooh I might have to implement this. Too may times I'm tab completing a command and get something I have no memory of installing and try to figure out what the heck it is
MeaningfulBits@jackwilliambell @troublewithwords good luck with that. We'll never agree on common syntax, not to mention most tool box everyday programs were written by a hippie 40 years ago for the Berkeley weekend LUG on shrooms as a dare.
@MeaningfulBits @jackwilliambell It's worth a shot. If we never tried anything because of what came before, we'd be in an even sorrier state.
@troublewithwords @jackwilliambell agreed it's just going to take 40 years. I always think something similar when I do -h... or --help... Oh f it, man pages I guess.
Hey Gus@jackwilliambell @troublewithwords this reminds me of cobra (go) and click (python) both having gentle and not so gentle nudges about documenting what each flag or option does.
Both awesome libraries for writing cli tools in those languages too.
> code is self documenting
I feel like people that are actually serious about what they're doing don't say this. Sure you can read a declarative program and see that given inputs go through a pipe to produce a thing but why by so snotty about it? It isn't like comments make you lesser in some way. It's more like gatekeeping the code because, uh, ego?
peter purgathofer@troublewithwords vaguely related: i once sat in on a master thesis defence where one of the interesting effects a student encountered was that code quality was better if the same code was prompted to generate WITH comments than rather without.