hachyderm.io is one of the many independent Mastodon servers you can use to participate in the fediverse.
Hachyderm is a safe space, LGBTQIA+ and BLM, primarily comprised of tech industry professionals world wide. Note that many non-user account types have restrictions - please see our About page.

Administered by:

Server stats:

10K
active users

THIS. So Much this.

This is what I am constantly trying to teach younger devs.

The best code is the most stupid-simple solution to the problem that runs in acceptable time.

The new intern fresh out of boot camp, with no understanding of the context should be able understand what it's doing.

Source: workchronicles.substack.com/p/
#programming

@masukomi @hrefna From an in-class activity I was just working up for the upcoming semester:

“In most circumstances, good code is not clever or complex; it is •obvious•.”

(Larger excerpt below for the curious. The activity involves reading different versions of English-language instructions for opening a door, ranging from absurd detail to “open the door.”)

@inthehands @hrefna agreed, but i think there is an important aspect it’s missing. It should be obvious to juniors and new hires with no institutional knowledge.

To often we write code that is obvious to people who’ve been there for years but may as well be a paragraph of random jargon terms to an experienced new hire without the context

@masukomi @inthehands @hrefna As a related kind of concept, while I'm working with adult learners in corporate software development settings, I take the time to explain the frustrations of overly complex functions in tandem with what good comments are.

Good comments to me tell me more about WHY you had to go through this crazy process in the first place and some reasoning behind the hoops. Bad comments only describe the complexity of the function as stated.

A good comment gives me the ability to refactor the logic and code into something else at a later date. A bad comment only tells me functionally what it does but not why it's significant or how much effort it will be to untangle this monstrosity.

To write better comments for yourself, write comments that tell you why this thing had to come into existence and when it is safe to vanquish back to the depths again when it's overstayed its welcome.

"Iterates over an n-dimensional tuple extracting x, y, z on each pass to pass to a lambda function ..." is so much less ideal to me as a corporate software developer than seeing "Extracts sales data by region because our existing API is missing this feature. Revisit later to see if this is necessary. Optionally here is a link to Issue #"

@gregdosh @inthehands @hrefna I am SO tired of arguing with "expert" programmers that think that because when _they_ read code everything is "obvious", that they spout the stupid "code should be self documenting" line. They never seem to "get" the things you said.

@dachary's a programmer/tech writer and her super-power is being able to put herself in the shoes of a reader who doesn't know anything and giving them the tools they need to succeed.

Paul Cantrell

@masukomi @gregdosh @hrefna @dachary
Yeah. It’s a tough one: there’s a whole lot to the idea that code should explain itself well, and I’ve definitely seen people lean on verbose, meandering docs that get stale fast when they should really have thought about renaming some things in the code first.

But that hard-core rejection of docs you describe is just…extremely unhelpful. (Perhaps born of a hostility to the humanities?)