# Meaningful Keyword or FooBar Placeholder?

As a self-taught (i.e. no college degree in CS) programmer, one question that I am always asking as I read documentation and tutorials is: *what are all the meanings and implications of this word being used?*
  
  ## The Pure Placeholder
  "Foo" and "Bar" are the commonly used words to signify a placeholder. Yet, this wastes an opportunity for extreme clarity. For example, let's say we're learning about a typescript interface: `export interface Foo`.   We're missing an opportunity to make it abundantly clear to the reader what is being named: `export interface TheNameOfOurInterfaceThatWeCanInstantiateLater`  The gratuitous verbosity when teaching (not when coding!) does 2 things: (1) drive home that this is a placeholder, there's nothing special about it, (2) reinforce *what* the thing is that we're talking about.
  
  Consider this c# method declaration:
  `public async Task<ActionResult<Results>> GetData()`.  That's 6 words/phrases, 4 of which have very specific meanings and origins, and 2 of which do not.
  
  `public` how we must prefix a c# method that we want to be callable outside this class
  `async` one piece of making this method asynchronous and defensive
  `Task` a builtin c# type that is being returned, specific to async methods. This type is generic in this usage.
  `ActionResult` a builtin c# type that is being returned, nested within the angle brackets. This type is also generic in this usage.
  `Results` would be better named `AnotherTypeOfADataStructureThatYouDefined`, a user-defined type that is being returned, nested further within the angle brackets
  `GetData` would be better named `MyUserDefinedMethodNameGetRecords`, name of your method
  
  The pedantic listing of terminology used, whether it's "part of" the language, or whether it's wording that is user-chosen, leaves no doubt in the reader how to implement the syntax.
  
  
  ## Conventions for Code Readability
  
  Backend data structures often have model classes that map directly to the database schema, along with json classes that may map directly to the model classes, but also may not. These json class names are often suffixed with `Json` (i.e. `OfficeFurnitureJson`) to be clear that this is a `Json` representation of the model class. BUT, it doesn't have to be named that. *Nothing special happens* because it's suffixed with `Json`. It's merely a convention that can be adopted by a codebase.
  
  The same idea applies to async methods being suffixed with `Async`.
  
  Since by nature bools are only TRUE or FALSE, a common pattern is naming Boolean variable names in question form, that is answered by the value of the bool: e.g. `isCatPettable`.   But just like the `Json` and `Async` suffixes, you gain no functionality by following this pattern/convention. It's merely there for code readability.
  
  Stating that using those words doesn't magically make it the thing you named it helps the reader understand clearly how they can apply the concepts in their own code.
  
  ## Special Names that do extra things in a specific context
  
  Think `ng onInit` or kotlin lifecycle methods like `onCreate()`.
  
  So much of learning programming is **patterns**, identifying them and using them. As I learned various programming languages and their syntax, a pattern that emerged was *"I can define whatever name I want for my method."* That's often true, but not always. Being clear about a method name being "special" allows the reader to continue mentally building on observed patterns, while creating a new pattern for this special case.
  
  The documentation IS quite clear on these sorts of methods. But it can be clearer about (a) these methods usually get called automatically (another commonly expected pattern is that you usually have to call methods for them to run), (b) they may have default functionality that is hidden AND a.gets run automatically, (c) they can be overriden with almost any functionality you want to put in there.
  
  Another example: Gitlab  WIP prefix. The documentation is very very clear on the purpose here. Just using it as an example of wording that absolutely is special and cannot be named whimsically. 
  
  ## Typescript Function calls within quotes
  
  If a TS function is defined `get returnCoolValue()` then it can be referenced in the template simply with `"returnCoolValue"`.  Again, as someone learning by creating mental patterns, if I only see this in the template, it doesn't automatically register as a function call; it seems like a variable reference. I'm not sure what I'm proposing here. Perhaps I'm proposing not doing this and just writing TS methods `returnCoolValue()` which then get referenced in templates with the bananas brackets. Perhaps I wish the language spec was different. At the very least, documentation should be abundantly clear that something that doesn't look like a method call in a template might indeed be a template call. 
  
  
  ## Default Vue app
  
  The default Vue app that gets created via `vue create....` uses "app" and "App" many many times, and they don't always refer to each other. It would be similarly unhelpful for documentation to be:
  ```
  public async Foo<Foo>(foo: foo) {
    foo = "foo";
    return foo;
  }
  ```
  
  Contrast with:
  ```
  public async MyMethodName<ReturnTypeClassName>(parameterClassName: myVariableName) {
    var myVariableName = "someStringValueImSettingItTo";
    return myVariableName;
  }
  ```
  
  To grasp the concept being taught, the reader is looking for words that match (and often assuming that they reference each other). 
  
  
  ## In Summary
  
  **Words and Terminology matter** (and not just in programming!). There's the actual value/meaning. There's the meaning the writer/teacher is intending. There's the meaning the reader/learner learns or assumes. **Any mismatch and learning is hindered.**
  
  Patterns matter. Pay attention to when a pattern is broken or doesn't hold. This is equally important when teaching as when learning.
  
  A sub-point of both points above is that in programming, it's assumed by anyone learning that symbols have specific meaning. They almost always do. Words sometimes do but sometimes *don't*.
  
  Finally, prioritize clarity above all else when writing documentation or verbally teaching concepts. You have the luxury of already knowing the concept. It can be easy to overlook the embedded knowledge that would add crucial context to what you're teaching; context that the learner may not have.