Follow

Still some of the best advice for programmers:

Don't be clever. Be obvious.

@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 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.

@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 those who want to be "clever" have not yet learnt that that does not demonstrate their skill.

Being obvious is far harder!

@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.

@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.

@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

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!