Follow

Still some of the best advice for programmers:

Don't be clever. Be obvious.

@fribbledom
Along the same lines with driving:

Don't be nice. Be predictable.

@russsaidwords @fribbledom THANK. YOU. I can't tell you how much more satisfying it is to deal with someone on the road driving fast or aggressive, so long as they are both predictable and committed, than it is to be behind someone bloody dawdling along at 20-below the limit, too timid to make a turn, and who freaks out (and swerves into the on-coming traffic lane almost completely) when they happen to pass a car parked along the side of the road.

@russsaidwords @fribbledom I get as mad at people who refuse to take the right of way as tailgaters, tbh

@fribbledom I spent a ton of time this week digging in the Git history for a string that was interpolated but could have been hardcoded. Not fun.

I never did find the code I was looking for.

@fribbledom "It pays to be obvious, especially if you have a reputation for subtlety."

@fribbledom i'm more from the "it was hard to write, it should be hard to understand" school of thought myself ;-)

@thamesynne @fribbledom I like to think my Altivec implementation of a Lanczos filter for video rescaling was easily readable. ^_^

@thamesynne @fribbledom We believe in disguising code that is hard to read by over-documenting what it's doing.

@thamesynne @fribbledom Bigger challenge is to make something that was hard to solve, easy to read. Leaving it hard to read is settling.

@fribbledom
There are rare cases when I write some clever code.
In those cases the comments are often as long as the code, or longer.

@fribbledom I went through a period of time when I fought myself on intermediate variables in calculations, but man it's nice to be able to step through (or even console.log) those results.

@tewha @fribbledom I'll avoid using intermediates if the expression is simple enough to fit on one line, maybe two. Beyond that, I use intermediates extensively.

@vertigo @fribbledom Yeah, the 1-2 line thing is my problem. Exactly where do I break that (if I break it) so I don't regret it later?

At this point I most often consider what the intermediates are and if it makes sense to inspect them and if they can be given a proper name. Sometimes I change operations around a bit just to get meaningful intermediates. I think it helps read, too. :)

@vertigo @tewha @fribbledom I like to show my work because it makes the logic easier to change in the future when the business change their mind on requirements.

@gws @tewha @fribbledom Just to clarify what I consider "simple enough," it's code that follows this form (in Python pseudocode):

def some_func(x,y,z):
return foo(x, y, bar(z, other_stuff))

Sometimes, if the symbol names are too long:

def some_func(x, y, z):
return foo(
x, y,
bar(z, other_stff)
)

that's what I mean by "one or two lines." If it grows beyond that, context is lost and/or becomes harder to change with evolving business requirements.

@vertigo @gws @tewha @fribbledom Totally. You're forced to when calling big-platform APIs because they never want simple parameters, it's always adapter this and factory that.

@vertigo @gws @tewha @fribbledom
And then *some people* like to write this as a one-line return expression:

def can_we_do_the_thing(policy, user, agent):
policy_status = api.isPolicySetUp(policy)
allow_override = user_is_cool && some && business && logic || other_case || yet_another_case
agency_status = agent.Agency.Status == 'yep'

return (policy_status && agency_status) || allow_override

@gws @tewha @fribbledom Yeah, that is a rather egregious violation of programmer decorum, for me. At the very least, split the operators onto separate lines (for compiled languages like C/C++, doing that helps because you can still single-step those lines).

@gws @tewha @fribbledom
Forth programming practice suggests that we should never deal with more than three items on the stack at any given time. This "rule of three" seems to be useful as well in non-Forth languages too. If you need 3 or more elements in a single expression, that's a smell that you might want to refactor that code.

@fribbledom And if you must be clever, comment your code.

@Felthry @fribbledom Heh I was just going to write this too:

"If you must be clever, be documenting!"

@fribbledom I always feel like "clever" is one of the more damning things code can be described as.

@fribbledom Being clever — making the reader / listener solve riddles — often waste of brainpower.

@fribbledom those who want to be "clever" have not yet learnt that that does not demonstrate their skill.

Being obvious is far harder!

@fribbledom gonna ruin everyone's day by writing for(;stuff(););

@fribbledom

1. write comments that describe your algorithm with pseudocode

2. implement EXACTLY what those comments say

3. stop programming. you are done. do not try to improve it.

@wersimmon @fribbledom I mostly program by opening a text editor, staring at it for an hour, and then writing one (1) line of code.

@ben @fribbledom I had arguments with people at work about this. There's a guy who said that he doesn't believe in comments, because the code is the best documentation, and comments get out of date (and are thus deceptive). And I was like... uh... so in 6 months when we hand this to a new person, they'll know intuitively what you meant by this, right? =_=

I agree that comments shouldn't == code, but it seems silly to omit the comments. On the flip side, there was a guy at a previous job who liked to do this:

// return this.
return i;

@feathers @fribbledom comments show what the code at one point in the far past was supposed to do (but didn't)

@ben @fribbledom Yeah. I always felt like the best comments describe intent. You don't explain how you're going to do a thing step by step (unless the code is somehow that difficult in its minimally difficult form) but rather why you're doing it, and the overall gist of how/why.

// First we'll do X, then Y, and Z <- bad comment
x; y; z;

// This performs the foobly transform to give us W
// <more info link>
x; y; z;

Eh I'm probably preaching to the choir... lol.

@ben
Not a big fan of pseudocode comments. Sooner or latter the pseudocode and the code *will* diverge.

Better to document expected input, outputs and underlying assumptions. The code itself can then be unit-tested.

@fribbledom

@fribbledom that's actually good advice for anyone designing something to be used by other people. the more obvious and simple it is, the easier it is to pick up and use properly.

@hawkjohenson

Remember that “other people” includes ourselves when revisiting the code weeks, months or years latter!

@fribbledom

@fribbledom But you've got to be clever to be obvious, if "being obvious" isn't to mean "well of course I understand it".

@fribbledom If you must be clever, document the shite out of it, and be clear with the how and why of your cleverness.

Sign in to participate in the conversation
Mastodon

Follow friends and discover new ones. Publish anything you want: links, pictures, text, video. This server is run by the main developers of the Mastodon project. Everyone is welcome as long as you follow our code of conduct!