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.
@Sylvhem yes, i agree there are places in mastodons codebase where the use of comments is obfuscatory and misleading.
@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 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?
@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 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
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.
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.
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
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.
@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)?
@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.
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.
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.