Follow

THE PRIMARY FUNCTION OF CODE IS TO BE READ BY HUMANS

@er1n @nightpool Commenting can be duplication of the code itself and allow the developer to get away with unreadable code. Commenting should be reserved for explaining choices or provide external context, not explain what the code does, which should be expressed through code itself (unless you are writing an unreadable language like assembly)

@gargron @er1n context changes, choices evolve. Every codebase is a flowing river and context that may have been applicable when you wrote the comment is almost certainly not applicable anymore. Decisions and context should be historical records in your version control system, not part of your codebase.

the inevitable cheap joke off this 

@nightpool assert(isinstance(self, Illusion))

@nightpool And this is why nobody really understand how Mastodon works 🎶.

@Sylvhem yes, i agree there are places in mastodons codebase where the use of comments is obfuscatory and misleading.

@nightpool On the contrary, I think there should be more comments in Mastodon's code ^^'.

@nightpool I haven't contributed in almost a year, so not really ^^.

@Sylvhem Okay. In general, I think mastodon's codebase should be much less confusing, and that comments are a shortcut that makes code less confusing in the short term but way more confusing in the long term.

@nightpool

Looks like *someone* has been reading Kent Beck.

(I generally agree with you, BTW.)

@nightpool I suppose you think comments are only necessary if your code isn't clear

@nightpool they are a necessary concession for languages that are not particularly legible though, right? Or should we just stick to the simplest constructs in every language and sacrifice efficiency to legibility?

@nightpool the primary function of code is also to be *used* by humans, albeit sometimes indirectly

@typhlosion the *primary* function of code is to be read by humans. you can't have two primary functions.

@nightpool in what way is the primary function of code not to be run by a computer and do computations

@typhlosion @nightpool because it usually gets compiled to code that gets run by a computer

@typhlosion the reason we have coding languages is to express computations in a way that humans can understand and reason about. the primary purpose there is reading + authorship. If we just cared about execution then we'd all still be writing assembly

@nightpool i'm not sure i buy this. communication with other humans isn't the only goal or the only benefit; higher-level programming languages allow us the coders to make logical shortcuts that allow us to more easily develop complex algorithms. i would never have the patience to do game development in raw assembly

while i agree it's important we write code so that others can easily read it, i wouldn't go so far as to say that communication with other humans is the *primary* function

@typhlosion "us the coders" *are* other humans though. when you say higher-level languages allow us to make logical shortcuts, what that unpacks to is that we're communicating and expressing ourselves more efficiently.

@nightpool be it to the hardware directly or to the software intermediaries that go between us and the hardware, we are communicating to a computer what we want it to do. communication with other humans about what we want the computer to do is equally important but i would hesitate to call it primary

@typhlosion @nightpool I didn't see it (typing our toots about the same time?) but the point still stands.

You are not communicating to a computer what you want to do when you write C. You are communicating to yourself what you want the compiler to translate into instructions for the computer.

Absent the compiler (which is not the computer, but another expression of human want-to-do), the C source file has zero communicative value to the computer.

@beadsland @nightpool "absent the compiler", you're just writing text into a document when you're writing code, so yeah, i guess i agree that in that strange vacuum you've constructed the primary utility of code is communication with other humans

@typhlosion @nightpool Computing is definitely a strange vacuum, but not unprecedented.

Consider the analogous case of building construction. An architect draws up plans that communicate the structural features of a building, but those plans take too may shortcuts to instruct a crew responsible for assembling that building.

Instead, those plans are translated, at multiple points, to communicate to various stakeholders and gatekeepers and suppliers and contractors as needed for comprehension.

@beadsland @nightpool just because the workers can't directly use the original plans doesn't mean the goal of the plans isn't for the house to be built

@typhlosion @nightpool Just because the computer can't directly use the C source file doesn't mean the goal of the code isn't for the program to run.

But that's the goal of the person drawing the plans / writing the source file. The goal of the computer is to follow instructions involving memory addresses and registers. The goal of the work crew is to follow instructions involving materials and specialized equipment.

The goals at the higher level of abstraction organize the goals at the lower.

@beadsland @nightpool you're still communicating to the computer what you want to happen! even if there's indirection involved! if im at a restaurant in barcelona with an english to german translator, a german to polish translator, a polish to mandarin translator, and a mandarin to spanish translator, my intent is still to get some fucking soup eventually

@beadsland @nightpool i genuinely can't follow your logic at all at this point and i'm getting agitated so i need to step away

@typhlosion @nightpool Ah, but here is where the word "translation" fails. Go through multiple stages of human translation, hopefully the chef at the other end prepares some soup.

But the goal to get a list of addresses sorted is never communicated to a computer. It never makes your bowl of soup. It assembles bytes into an order that you interpret as soup, but it never does anything involving soup or lists of addresses or whatever.

Per your follow-up toot, mutually stepping away at this point.

@typhlosion @nightpool Computers can't make heads nor tails of higher level languages. They need to be translated, and not merely to assembly (which already uses mnemonic vocabulary for the benefit of humans--thus not "raw", as such) but to raw machine language.

If you're writing in anything but base-something representations of opcodes that execute directly on the processor, you're writing for the benefit of humans. So far as a computer is concerned, C and Lisp are equally incomprehensible.

@beadsland @nightpool did you intentionally ignore the follow-up i wrote to explain myself better or did you just not see it awoo.space/@typhlosion/1029960

@nightpool @typhlosion Seems quixotic. I'm 90% of coders aren't going to understand, say, the GEANT2 code no matter how well written it is, due to them not understanding nuclear physics.

@Canageek that's okay, your target audience can just be "other nuclear physicists" or "me but in the future", but it's still the primary purpose of your code.

@nightpool I disagree? The primary purpose of the code is to do nuclear physics math. Once it is verified correct no one is going to be looking at it for a few decades anyway....

@Canageek but in a few decades people will need to look at it again!

the primary purpose of the *project* may be nuclear physics math, but the primary purpose of *code*, as a tool in that project, is communication.

@nightpool No, at that point it would likely be rewritten if a problem was found in it, as you'd need the old stuff around to verify old calculations and compare them to the new version.

No one reads nuclear physics code for fun. It is a tool. Like a hammer.

@Canageek i'm not sure where you got "for fun" in the thing I was saying. reading code is a *fundamental part* of understanding and authoring code.

@nightpool Why else would you read code that a team of physicists at CERN has already verified gives you the correct results (within the known limitations of that model, anyway)?

@Canageek i'm saying *that verification is a form of reading the code*

@nightpool The verification may not in fact involve reading the code, it may involve running it against other known model and making sure the results match, or against hand-done calculations. Reading the code and making sure it is correct is only part of that.

@Canageek @nightpool Dijkstra's dreams notwithstanding, very few programs are verifiable as "correct".

At best, we can verify that for the cases we've anticipated testing against known outcomes, we get the outcomes we know we are anticipating.

But even where verification of correctness is possible, one still must read what one is editing in the course of the testing and revision cycle. GEANT2 code is geared toward readability by nuclear physicists in a way that machine opcodes are not.

@nightpool Nah, the primary purpose ("function" is confusing between technical and sociological meaning) of code is to convert my coffee into swearing.

Secondary is to let me organize code faster than writing ASM macros; not a huge deal, but existent.

Tertiary is to let compilers more efficiently compile; raw ASM by a human won't be as good as abstract code run thru an optimizing compiler, hasn't for 20+ years.

Maybe quaternary is communication with others. What programmer cares about Humans? Ew.

@mdhughes @nightpool Recap:

Primary purpose: convert coffee into offensive human spoken communication

Secondary: organize written communication faster than another form of written communication (specifically written shorthand in the form of macros)

Tertiary: allow written ideas to be optimized more efficiently, such that the programmer can focus on writing what they want to do rather than specifying exactly how to do it

Maybe Quaternary: human interaction, but only if absolutely unavoidable

@beadsland @nightpool Very few Humans have to tolerate my code-swearing anymore, but theoretically yes, a Human might hear me and think I was communicating with them, and I feel very sorry for them in that case.

2 & 3 are purely for the machine. I used to type in BASIC program listings, I'm patient in a way tortoises and glaciers might find obstructionary, but computer time is limited.

@mdhughes @nightpool The computer has no concept of patience. It has exactly as much time with itself as it needs to be itself. If you're impatient, and using a programming language to alleviate your impatience, that's purely for you, not the machine.

Not only does the computer not care how long it takes to do what you want to do, it doesn't care how long it takes you to communicate what you want to do, or even if you ever successfully communicate what you want to do. These are human concerns.

@nightpool There was me thinking the primary function of code was to run and do something.

Sign in to participate in the conversation
Cybrespace

cybrespace: the social hub of the information superhighway jack in to the mastodon fediverse today and surf the dataflow through our cybrepunk, slightly glitchy web portal support us on patreon or liberapay!