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 it sure is nice not having comments to understand design choices, algorithm details and make more explicit what magic frameworks do

@Thib design choices are a function of the context the code was written in, and that context is ever-evolving. Keeping outdated contexts around is just as bad as not having any to begin with—often even *worse*, if they're misleading!

algorithm details should be expressed as simply as possible. For any possible written explanation you can give, there is an equivalent coding structure that's just as easy to understand.

@nightpool if the context is explained you can check if it's still up-to-date. If it's not, you can spend ages figuring out why the fuck you did something in a specific way and either not change it out of fear of breaking things, or change it and break things you didn't expect

sarcasm 

@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 to add to the bullshit pile, i Do Not Agree

a lot of comments are useless, a perfect programming language should not push you to use a lot of comments, but still i think there's a gap between "what the computer needs to know" and "what a programmer needs to know" that is solved by comments and proper naming, and that can't be solved by changing the language without falling into an endless pit of trying to program in plain english with a magical compiler

@nightpool typically a short summary of a module or function. could the language be such that those could be inferred by the computer solely to be displayed to a programmer? surely it is redundant information. yet we can't possibly expect a computer to guess why this bit of code is important or why it was made in such way. this is not part of the program itself, it's metadata by and for programmers

@CobaltVelvet the whole point of this toot thread is "what a computer needs to know" is the least important thing when you're writing code! your code should express, clearly and succinctly, *what a programmer needs to know when working on it*

@CobaltVelvet
proper naming is a great example of why changing the code is better then writing comments. instead of having to add the cognitive burden of remembering "okay X means the vm we're trying to update because this comment said so", you just write "vm_to_update" and move on with your life.

@nightpool ye it didn't mean bad naming (or lack of) is solved by comments, but analogous to it. it's information inherently useless to the computer but not to the programmer

@CobaltVelvet yes. I think you're maybe misinterpreting me. when I say "the primary function of code is to be read by humans" I mean that you should *first and foremost* think of the information useful to the programmer, and encode that in your program, and only secondarily think of information that is useful or required by the computer. comments are what happen when you try to tack that structure or information on on as an afterthought

@nightpool but are they though. how do you encode the reason for choosing a specific algorithm? should you even attempt to encode that? what about writing a summary for a module? i'd think even with perfect naming and perfect language, you can hardly encode the reasoning behind why your code is structured in such way, while it is important information, possibly because this hardly has a place outside comments or other documentation.

@nightpool ugh i guess what i fundamentally mean is, however abstract and perfect your code gets, you'll always have to document some Whys when it answers Hows, even if it ends up being a readme.md or in an help menu.

@CobaltVelvet i dunno, i think good naming and structure can really help with most whys! I absolutely don't think that they're a substitute for design docs, but like.... you can get pretty far.

i'm also not at *all* saying you shouldn't write long-form prose or documentation about your code! I'm saying that comments, specifically, are a bad compromise for information that is usually better presented 1) by the code itself or 2) in ancillary documentation, like commit messages, design documents, and readmes

@nightpool @CobaltVelvet I don't know, commits messages are useful, but relying on it for explaining the Why means you have to tediously track changes through the commit log as soon as there are refactors or such touching that piece of code after the commit explaining the Why.

READMEs and Design documents are definitely useful, but sometimes it just makes more sense to have the information (or, a link to a Design document, for instance) readily available in the part of the code that matters.

@nightpool but aren't comments a reasonable way to embed documentation and design docs close to implementation, for things that aren't very useful separately

surely not the best way or the only way, but a way that Sometimes is the most appropriate

@CobaltVelvet @nightpool can I add my 50c?
Code explains What as much as it can. It cannot always explain all domain logic.
Comments first and foremost explain Why that code is there. That's sometimes domain, sometimes nonobvious choices.
vcs explains Why This Change was made at this point of time.

@charlag @CobaltVelvet but intent isn't static just like code isn't static. The code that you might have thought was primarily for inter-server communication might be used for public federation way down the line! comments become misleading way more easily then code does, since nothing breaks if they're wrong.

@nightpool @CobaltVelvet so do names? If you go on and rename ClientService into NetworkCommunicationService you probably will go and update many things, including doc comment and names?
I think this reasoning doesn't work. You can change code in a way that it won't break but won't have the same use as well as the other way around. There's not much in the code itself except names that communicates the intent.

@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

Sign in to participate in the conversation
Cybrespace

Cybrespace is an instance of Mastodon, a social network based on open web protocols and free, open-source software. It is decentralized like e-mail.