Skip to content

Commit

Permalink
docs: notes on Programmer's brain
Browse files Browse the repository at this point in the history
  • Loading branch information
@butuzov
butuzov committed Jan 17, 2022
1 parent a84fc89 commit ce8bd4e
Show file tree
Hide file tree
Showing 2 changed files with 417 additions and 11 deletions.
267 changes: 258 additions & 9 deletions reading/Programmers_Brain.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@
"id": "1395401b",
"metadata": {},
"source": [
"# Programmer's Brain"
"# Programmer's Brain\n",
"\n",
"\n",
"Notes on https://www.manning.com/books/the-programmers-brain "
]
},
{
Expand All @@ -24,6 +27,20 @@
"### Decoding Your Confusion While Coding"
]
},
{
"cell_type": "markdown",
"id": "d21c2574",
"metadata": {},
"source": [
"Confusion\n",
"\n",
"It identifies three things. Lack of Knowledge, Lack of Information and Lack of Processing Power.\n",
"\n",
"- lack of information - basically, you don’t know enough about the project / code you are looking at\n",
"- lack of knowledge - you lack knowledge about the thing you are doing, i.e.: some obscure language syntax you are unfamiliar with\n",
"- lack of processing power - the code chunk you are looking at is too large, or you should break it down\n"
]
},
{
"cell_type": "markdown",
"id": "d0a289bc",
Expand Down Expand Up @@ -218,6 +235,19 @@
"### Getting Better At Solving Programming Problems"
]
},
{
"cell_type": "markdown",
"id": "39b8b8d5",
"metadata": {},
"source": [
"What **mental models** you will use to think about code partly depends on the domain, the programming language, and the architecture of the code. However, some things are generally worth using:\n",
"- Data structures, such as directed and undirected graphs and different forms of lists \n",
"- Design patterns, such as the observer pattern\n",
"- Architectural patterns, such as Model–View–Controller\n",
"- Diagrams, such as entity relationship diagrams or sequence diagrams\n",
"- Modeling tools, such as state diagrams or Petri nets\n"
]
},
{
"cell_type": "markdown",
"id": "f73c35db",
Expand All @@ -231,6 +261,33 @@
"### Misconceptions: Bugs In Thinking"
]
},
{
"cell_type": "markdown",
"id": "f92300e9",
"metadata": {},
"source": [
"In regular conversation, the word “misconception” is often used as a synonym for a mistake or for being confused, but the formal definition is slightly different. For a belief to be a misconception, it must:\n",
"- be faulty,\n",
"- be held consistently, across different situations, and \n",
"- be held with confidence.\n"
]
},
{
"cell_type": "markdown",
"id": "128674c6",
"metadata": {},
"source": [
"Summary:\n",
" \n",
"- Knowledge you already have stored in your LTM can be transferred to new situ- ations. Sometimes existing knowledge helps you learn faster or perform new tasks better. This is called positive transfer.\n",
"- Transfer of knowledge from one domain to another can also be negative, which happens when existing knowledge interferes with learning new things or exe- cuting new tasks.\n",
"- You can use positive transfer to learn new things more effectively by actively searching for related information in your LTM (for example, by elaboration, as covered earlier in the book).\n",
"- You may hold misconceptions, which occur when you are sure you are right but are actually wrong.\n",
"- Misconceptions are not always addressed by simply realizing or being told you are wrong. For misconceptions to be fixed, you need a new mental model to replace the old, wrong model.\n",
"- Even if you have learned a correct model, there is always the risk you will fall back to using the misconception.\n",
"- Use tests and documentation within a codebase to help prevent misconceptions."
]
},
{
"cell_type": "markdown",
"id": "ace02d37",
Expand All @@ -247,6 +304,42 @@
"### How To Get Better At Naming Things "
]
},
{
"cell_type": "markdown",
"id": "f3082520",
"metadata": {},
"source": [
"https://peter.bourgon.org/blog/2019/04/24/go-naming-tips.html\n",
"\n",
"- Structs are plain nouns: API, Replica, Object\n",
"- Interfaces are active nouns: Reader, Writer, JobProcessor\n",
"- Functions and methods are verbs: Read, Process, Sync"
]
},
{
"cell_type": "markdown",
"id": "19ca37b5",
"metadata": {},
"source": [
"Feitelson designed a three-step model to help developers choose better names:\n",
"\n",
"1. Select the concepts to include in the name.\n",
"2. Choose the words to represent each concept.\n",
"3. Construct a name using these words."
]
},
{
"cell_type": "markdown",
"id": "e5a10997",
"metadata": {},
"source": [
"general tips\n",
"\n",
"- Make sure you completely understand the domain\n",
"- Simplify the code\n",
"- Avoid bad code and cognitive load"
]
},
{
"cell_type": "markdown",
"id": "6bc63c9f",
Expand All @@ -255,12 +348,85 @@
"### Avoiding Bad Code And Cognitive Load: Two Frameworks"
]
},
{
"cell_type": "markdown",
"id": "903eac56",
"metadata": {},
"source": [
"Refactorings defiend by Fauler's book (avoid it).\n",
"\n",
"#### Method Level\n",
"- Long Methods\n",
"- Long Parameter List\n",
"- Switch statements\n",
"\n",
"#### Class Level \n",
"- Alternative Classes with different Interfaces\n",
"- Primitive obsession \n",
"- Incomplete Library class \n",
"- Large Class\n",
"- Lazy Class \n",
"- Data Class \n",
"- Temp fields\n",
"- Data Clumps\n",
"\n",
"#### Codebase level \n",
"\n",
"- Divergent Change | Shotgun surgery \n",
"- Feature Envy\n",
"- Inappropriate intimacy \n",
"- Duplicate code or code clones\n",
"- Superflouse comments\n",
"- Message Chains \n",
"- Middle man \n",
"- Refused bequest \n",
"- Speculative generality "
]
},
{
"cell_type": "markdown",
"id": "90e6c046",
"metadata": {
"ExecuteTime": {
"end_time": "2022-01-17T13:29:14.225405Z",
"start_time": "2022-01-17T13:29:14.208652Z"
}
},
"source": [
"- `Structural`: Code is okay, but structured in a way that is difficult to understand and process -> increases cognitive load. \n",
"- `Linguistic`: Bad / misleading names lead to confusion and bugs."
]
},
{
"cell_type": "markdown",
"id": "33960e71",
"metadata": {},
"source": [
"##### Summary \n",
"- Code smells, such as long methods, indicate structural issues with code. There are different cognitive reasons why code smells cause a higher cognitive load. Duplicated code, for example, makes it harder to chunk code properly, while long parameter lists are heavy on your working memory.\n",
"- There are different ways to measure cognitive load, including biometric sensors like measuring blinking rate or skin temperature. If you want to measure your own cognitive load, the Paas Scale typically is a reliable instrument.\n",
"- Linguistic antipatterns indicate places in a codebase where code does some thing different than names involved suggest, leading to a higher cognitive load. This is likely caused by the fact that your LTM finds wrong facts while trying to support your thinking. Linguistic antipatterns can also lead to wrong chunking because your brain assumes a meaning of code that is not actually implemented."
]
},
{
"cell_type": "markdown",
"id": "23a014b8",
"metadata": {},
"source": [
"### Getting Better At Solving Complex Problemsaa"
"### Getting Better At Solving Complex Problems"
]
},
{
"cell_type": "markdown",
"id": "ceb2ca42",
"metadata": {},
"source": [
"> In 1945, Pólya wrote a short and famous book called How to Solve It. His book proposes a “system of thinking” to solve any problem involving three steps: \n",
"> 1. Understanding the problem \n",
"> 2. Devising a plan \n",
"> 3. Carrying out the plan\n",
">\n",
"> **However, despite the popularity of generic approaches, research has consistently shown that problem solving is neither a generic skill nor a cognitive process.**"
]
},
{
Expand All @@ -279,6 +445,45 @@
"### The Act Of Writing Code"
]
},
{
"cell_type": "markdown",
"id": "671fc6e5",
"metadata": {},
"source": [
"Activity | task: Executing | task: Coding | task: Testing | task: Reading | task: Refactoring | Hard On |\n",
"----------------|-----------------|--------------|---------------|---------------|-------------------|---------|\n",
"Searching |x| | |x| | Short-term memory\n",
"Comprehension |x| |?|x|?| Working memory\n",
"Transcribing | |x| | | | Long-term memory\n",
"Incrementation |x|x|x|x|?| All three\n",
"Exploration |x|x|x|x|?| All three\n"
]
},
{
"cell_type": "markdown",
"id": "51e85f95",
"metadata": {},
"source": [
"* __*Searching*__ - code searching.\n",
"* __*Comprehension*__ - When you are performing the activity of comprehension, you are reading and executing code to gain an understanding of its functionality\n",
"* __*Transcription*__ - Transcription is the activity where you are “just coding.”\n",
"* __*Incrementation*__ - Incrementation is a mix of searching, comprehension, and transcription. When you are incrementing a code base, you are adding a new feature, which is likely to include both searching for the location(s) to add code and comprehending the existing code to understand where to add code and how to do that, followed by the actual transcrib- ing of the idea into syntax.\n",
"* __*Exploration*__ - When you are performing the activity of exploration, you are in essence sketching with code. You might have a vague idea of where you want to go, but by programming you gain clarity about the domain of the problem and about the programming constructs you will need to use."
]
},
{
"cell_type": "markdown",
"id": "1a9c975a",
"metadata": {},
"source": [
"##### Summary \n",
"- When you are programming, you perform a combination of different program- ming activities: searching, comprehending, transcription, incrementation, and exploration. Each activity puts pressure on different memory systems. There- fore, each activity should be supported by different techniques.\n",
"- Interruptions while you are programming are not only annoying; they are detri- mental to productivity because it takes time to rebuild your mental model of the code.\n",
"- To better deal with interruptions, offload mental models into notes, documen- tation, or comments.\n",
"- Deliberately support your prospective memory if you cannot complete a task by documenting your plans.\n",
"- Try to limit interruptions to moments you experience low cognitive load, for example, through automation using a FlowLight or manually by setting your status in Slack.\n"
]
},
{
"cell_type": "markdown",
"id": "dbc20fc6",
Expand All @@ -289,28 +494,72 @@
},
{
"cell_type": "markdown",
"id": "928feda3",
"id": "bdb8617f",
"metadata": {},
"source": [
"### How To Onboard New Developers"
"#### `CDCB` cognitive dimension of codebases"
]
},
{
"cell_type": "markdown",
"id": "6c6aff0b",
"id": "e3dde840",
"metadata": {},
"source": []
"source": [
"- **Error Proneness** This one is mostly about type safety and how easy it is in your code to make errors.\n",
"\n",
"- **Consistency** How consistent is your code with itself. Naming, structure, where and why things are where they are. Paradigms, idioms being used…\n",
"\n",
"- **Diffuseness** How much space a programming construct takes. How long certain required syntaxes are. Things like for loops, and language structures. How compact or extent the code is.\n",
"\n",
"- **Hidden Dependencies** How visible are the code’s dependencies. Are there hidden things the user needs but is not apparent and not documented?\n",
"\n",
"- **Provisionality Exploring** ideas can help when writing code. You start writing and that will give you ideas about how to proceed further. Your vague ideas become more concrete. Some language can be used better to do this because they don’t get in your way. Like Python, JavaScript. Go is strictly typed and will scream at you if you make a mistake. That can hinder exploration.\n",
"\n",
"- **Viscosity** How resistant is your code to changes.\n",
"\n",
"- **Progressive Evaluation Similar to Provisionality, this dimensions defines how hard it is to execute partial code.\n",
"\n",
"- **Role expressiveness** How easy it is to see what does what. Like, in Ruby it’s difficult to see if something is a function call or a variable. thing.other. Other might be anything. Meanwhile in other languages it’s easy to see that thing() is a function.\n",
"\n",
"- **Closeness of Mapping** How close your program is to the domain / problem that is solved.\n",
"\n",
"- **Hard Mental Operations** The code requires hard mental operations, such as, deciphering obscure syntax, or understanding hard idioms like monads and difficult to follow type systems. If your project requires hard mental operations, contributors are less likely to join it.\n",
"\n",
"- **Secondary Notation** This one is weird. Second meaning to code, such as comments and named parameters.\n",
"\n",
"- **Abstraction** Can users of your system create their own abstractions which are as powerful as built in abstractions. For example functions in a programming language. In Go I would say interfaces provide this abstraction since a user of a Library can create their own Interface over some functionality of a library and use that and pass in the libraries function.\n",
"\n",
"- **Visibility** How easy is it to see parts of the system. Is your folder structure following your architecture layers?"
]
},
{
"cell_type": "markdown",
"id": "5b053487",
"id": "928feda3",
"metadata": {},
"source": []
"source": [
"### How To Onboard New Developers"
]
},
{
"cell_type": "markdown",
"id": "9beda4c5",
"id": "f74694ee",
"metadata": {},
"source": [
"- **Don’t overload newcomers**. They need to learn a LOT about your environment, group dynamic, team procedures, issue handling, break routines… and I didn’t even begin talking about code yet…\n",
"\n",
"- **Once you master something you forget how difficult it was**. This is a great point we tend to forget. You have a better view of the big picture. You know parts of the code better. Beginners tend to focus on detail more and don’t see the big picture yet. You tend to think that that stuff is “easy”. Since you already forgot how difficult it is/was.\n",
"\n",
"- **Noticing patterns**. Even if you don’t immediately have an answer to a problem you’ll be faster in finding it. You can chunk code better, you can read code faster and spot certain patterns more efficiently since you already encountered them a hundred times over.\n",
"\n",
"- **Semantic Wave** This one is a really interesting concept. It depicts the ideal learning curve of a newcomer. Coin by Karl Maton. Read about it here."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "33acd552",
"metadata": {},
"outputs": [],
"source": []
}
],
Expand Down

0 comments on commit ce8bd4e

Please sign in to comment.