david-fong/00-people-friendly-programming-words.md

## 00-people-friendly-programming-words.md

      
    Raw
  

              00-people-friendly-programming-words.md
            
          
    People-Friendly Programming Words

Programmers use many words that don't translate well to their intended meanings. Jargon is a learning hurdle, and it creates a language gap between programmers and the general public. This document contains my ongoing pursuit of words for programming that are friendlier to people in general.


Avoid choosing names / name-fragments that have meanings other than the specific meaning that needs a name.


If a meaning already has multiple names commonly used outside programming that have equal unambiguity, choose the one that a person is most likely to have learned first.


For meanings which do not have any names commonly used outside of programming, try to find a combination of names.


Do not touch names of standardized protocols and encoding schemes and such (ex. http, floating-point, 2's-compliment signed integers, utf8, ascii, png, etc.), and always follow terminology used in protocol/encoding specifications, unless the communities developing them expressly desire that the terminology be changed in the future.


Programmer Lingo


Instead Of
Use
Why


fix bug
correct mistake
"bug" doesn't translate literally to anything relevant to what programmers mean it to be. In regular-people-talk, a bug is a sentient, small, and sometimes annoying being. Programmers have shifted to talk about bugs as if they just appear out of nowhere to mess them up (there is no implication of it being caused by somebody), and that they are consigned to the chore of retroactively getting rid of them. What programmers really mean is "unintended and undesired behaviour that was discovered after believing that a solution was ready for use; usually as a result of a lack of thorough checking of the correctness of a solution, whether due to lack of experience ( including insufficient understanding of a tool or problem), operating on a time constraint, laziness, etc." In other words- "a mistake"- and usually an honest one (ie. not due to laziness / disdainful carelessness). A mistake is a mistake, and honest mistakes are nothing to be ashamed of. Let's just call it what it is.


comment
explainer
"Comment" does not imply any degree of usefulness. In fact, "passing comment" is a common phrase meaning "a cheap personal remark made without a direct intention to benefit the receiver", which is totally contrary to what code "comments" are supposed to do. What programmers really mean is "text embedded alongside the code to aide a reader in understanding code they aren't familiar with." Ie. an explainer. "Explainer" can leverage the common wisdom that the obvious doesn't need to explained, which is a common misuse of code "comments".


Organization


Instead Of
Use
Why


namespace / module / package
place
I think the least ambiguous word we use is "namespace", but I don't think any person will figure out what we use it to mean until it's explained to them. I thought of the word "folder", which is friendly to most people who use computers, but "place" is even more generally understood. It may be a bit confusing that compilers choose optimized placements, but I think that is a simple enough fact to teach beginners (the possible confusion is small, and easy to clear up early on).


Functions


Instead Of
Use
Why


function
action / calculation
"calculation" for pure functions. I don't really want to use "function" because in math, a function isn't something to be "called" or "performed", and is generally understood to not affect any "state" except when state is explicitly a parameter.


function parameter / argument
need
(I'm iffy on this one.) "Need" has a nice property of being both a verb and a noun, which decreases the amount of lingo: we no longer need to have the word "take" (as in "function has parameter which takes argument"): all of "parameter", "argument", and "take" are replaced by "need", which is kinda nice. If I decide to keep with the word "function", I'll probably go with "input" here. I anticipate it being confusing how "need" sounds when you want to specify an optional / "maybe"-type value, but I think it's still a liveable offence, especially since "need" will not be written in the code.


return /return value
answer
To the average person, the most common meaning of the word "return" means "to give back something that was borrowed". "Answer" goes well with the terminology of "call" and "function", but it doesn't go well with "action", so I'll have to think about that. "Answer" also has the nice property of being a verb and a noun.


call
do
"do" works better with "action"


Common Statement Keywords

I will try to consistently choose verbs as statement keywords. I think it will be easier on the mind to have a consistent "POV". Using verbs gives the POV of instructing the computer / runtime what to do. I will also try to choose words that don't feel out of place for very low or high-level programming.


Instead Of
Use
Why


var / val / let / const / def
have
I want to choose a really short (in terms of characters) and simple word that implies at least a little bit of relation to allocating "physical", stateful memory space. "var", "val", and "const" aren't verbs, and "let" and "def" feel very math-y and theoretical to me- describing stateless relations kind of like combinational logic in hardware-description languages.


Classes And Types


Instead Of
Use
Why


field / member variable
part


interface / virtual functions
trait
(Piggybacking off of Rust here). "Trait" is an uncommon word, but it's meaning is suitable. The word "interface" is quite broad, and doesn't work as well languages that don't defaults methods to be virtual functions. Interestingly, I think friendliness to the general public is not very helpful here, since virtual functions are a pretty specific mechanism; having a less common word may help when learning it.


extends
embeds
Runner ups: integrates / implants / ingrains / attaches. I'll talk more about this later. I want to expose "extension" more as a special kind of "composition".


abstract methods
embedder trait


VCS


Instead Of
Use
Why


commit / version
update
Unlike "commit", "update" is naturally both a verb and a noun. I'm wary that "update" could be conflated with a "release", so that distinction will need to be made clear. The difference between "version" and "update", is that "update" implies a direction, whereas "version" does not (similar to the distinction between a list and a set). I would discourage mixing the words because it results in the mental overhead of having an intuitive comparison of them as an update being a change and a version being the result of a change, but then using the words to name one thing.


pull-request / branch
update proposal
(First of all- yes, I am combining PR branches and PRs. I'll explain more later.)


Misc


Instead Of
Use
Why


string
utf8 text, ascii text, etc.
The historical rationale for the choice of the word "string" was pretty ridiculous. By the same logic, "string" could mean an ordered collection of pretty much anything. "string" carries no information about what the encoding is, and I think being aware of common encodings is important to non-beginners. Discourage using anything other than utf8 except when necessary to interface with things that insist on anything else. See UTF-8 Everywhere.


array reduce
summarize
Instead Of	Use	Why
fix bug	correct mistake	"bug" doesn't translate literally to anything relevant to what programmers mean it to be. In regular-people-talk, a bug is a sentient, small, and sometimes annoying being. Programmers have shifted to talk about bugs as if they just appear out of nowhere to mess them up (there is no implication of it being caused by somebody), and that they are consigned to the chore of retroactively getting rid of them. What programmers really mean is "unintended and undesired behaviour that was discovered after believing that a solution was ready for use; usually as a result of a lack of thorough checking of the correctness of a solution, whether due to lack of experience ( including insufficient understanding of a tool or problem), operating on a time constraint, laziness, etc." In other words- "a mistake"- and usually an honest one (ie. not due to laziness / disdainful carelessness). A mistake is a mistake, and honest mistakes are nothing to be ashamed of. Let's just call it what it is.
comment	explainer	"Comment" does not imply any degree of usefulness. In fact, "passing comment" is a common phrase meaning "a cheap personal remark made without a direct intention to benefit the receiver", which is totally contrary to what code "comments" are supposed to do. What programmers really mean is "text embedded alongside the code to aide a reader in understanding code they aren't familiar with." Ie. an explainer. "Explainer" can leverage the common wisdom that the obvious doesn't need to explained, which is a common misuse of code "comments".
Instead Of	Use	Why
function	action / calculation	"calculation" for pure functions. I don't really want to use "function" because in math, a function isn't something to be "called" or "performed", and is generally understood to not affect any "state" except when state is explicitly a parameter.
function parameter / argument	need	(I'm iffy on this one.) "Need" has a nice property of being both a verb and a noun, which decreases the amount of lingo: we no longer need to have the word "take" (as in "function has parameter which takes argument"): all of "parameter", "argument", and "take" are replaced by "need", which is kinda nice. If I decide to keep with the word "function", I'll probably go with "input" here. I anticipate it being confusing how "need" sounds when you want to specify an optional / "maybe"-type value, but I think it's still a liveable offence, especially since "need" will not be written in the code.
return /return value	answer	To the average person, the most common meaning of the word "return" means "to give back something that was borrowed". "Answer" goes well with the terminology of "call" and "function", but it doesn't go well with "action", so I'll have to think about that. "Answer" also has the nice property of being a verb and a noun.
call	do	"do" works better with "action"
Instead Of	Use	Why
field / member variable	part
interface / virtual functions	trait	(Piggybacking off of Rust here). "Trait" is an uncommon word, but it's meaning is suitable. The word "interface" is quite broad, and doesn't work as well languages that don't defaults methods to be virtual functions. Interestingly, I think friendliness to the general public is not very helpful here, since virtual functions are a pretty specific mechanism; having a less common word may help when learning it.
extends	embeds	Runner ups: integrates / implants / ingrains / attaches. I'll talk more about this later. I want to expose "extension" more as a special kind of "composition".
abstract methods	embedder trait
Instead Of	Use	Why
commit / version	update	Unlike "commit", "update" is naturally both a verb and a noun. I'm wary that "update" could be conflated with a "release", so that distinction will need to be made clear. The difference between "version" and "update", is that "update" implies a direction, whereas "version" does not (similar to the distinction between a list and a set). I would discourage mixing the words because it results in the mental overhead of having an intuitive comparison of them as an update being a change and a version being the result of a change, but then using the words to name one thing.
pull-request / branch	update proposal	(First of all- yes, I am combining PR branches and PRs. I'll explain more later.)
Instead Of	Use	Why
string	utf8 text, ascii text, etc.	The historical rationale for the choice of the word "string" was pretty ridiculous. By the same logic, "string" could mean an ordered collection of pretty much anything. "string" carries no information about what the encoding is, and I think being aware of common encodings is important to non-beginners. Discourage using anything other than utf8 except when necessary to interface with things that insist on anything else. See UTF-8 Everywhere.
array reduce	summarize