Skip to content

Fix more markdown linting issues #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 22, 2024
Merged

Fix more markdown linting issues #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions advanced-tdd/01-advanced-tdd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ subtitle: Advanced TDD
| Chapter | Time |
| -------------------------- | -------- |
| Welcome | 00:00:47 |
| Core Collaps Supernova | 00:03:48 |
| Core Collapse Supernova | 00:03:48 |
| TDD Review: The Three Laws | 00:12:49 |
| The Single Assert Rule | 00:32:12 |

Expand All @@ -42,11 +42,11 @@ subtitle: Advanced TDD

# Timetable

| Activity | Time |
| ----------- | ------ |
| Warmup | 5 min |
| Excercise 1 | 10 min |
| Wrap up | 5 min |
| Activity | Time |
| ---------- | ------ |
| Warmup | 5 min |
| Exercise 1 | 10 min |
| Wrap up | 5 min |

# Warmup

Expand Down
10 changes: 5 additions & 5 deletions advanced-tdd/03-clean-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@ subtitle: Clean Tests

# Timetable

| Activity | Time |
| ----------- | ------ |
| Warmup | 5 min |
| Excercise 1 | 10 min |
| Wrap up | 5 min |
| Activity | Time |
| ---------- | ------ |
| Warmup | 5 min |
| Exercise 1 | 10 min |
| Wrap up | 5 min |

# Warmup

Expand Down
182 changes: 91 additions & 91 deletions fundamentals/02-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,49 +5,49 @@ subtitle: Names++

# Pre-work

* Video: <https://cleancoders.com/episode/clean-code-episode-2>
* Exam: <https://cleancoders.com/episode/clean-code-episode-2/exam>
- Video: <https://cleancoders.com/episode/clean-code-episode-2>
- Exam: <https://cleancoders.com/episode/clean-code-episode-2/exam>

# Chapters

| Chapter | Time |
|----------------------------|----------|
| Reveal Your Intent | 00:00:42 |
| Describe the Problem | 00:04:24 |
| Avoid Disinformation | 00:08:19 |
| Pronouncable Names | 00:13:24 |
| Avoid Encodings | 00:16:36 |
| Parts of Speech | 00:20:01 |
| The Scope Lengh Rule | 00:25:06 |
| Recap & Conclusion | 00:31:39 |
| Distance to the Sun | 00:36:07 |
| Chapter | Time |
| --------------------- | -------- |
| Reveal Your Intent | 00:00:42 |
| Describe the Problem | 00:04:24 |
| Avoid Disinformation | 00:08:19 |
| Pronounceable Names | 00:13:24 |
| Avoid Encodings | 00:16:36 |
| Parts of Speech | 00:20:01 |
| The Scope Length Rule | 00:25:06 |
| Recap & Conclusion | 00:31:39 |
| Distance to the Sun | 00:36:07 |

# Timetable

| Activity | Time |
|----------------------------|--------|
| Warmup | 5 min |
| Exercise 1 | 10 min |
| Exercise 2 | 10 min |
| Intro to technical writing | 45 min |
| Exercise 3 | 10 min |
| Wrap up | 5 min |
| Activity | Time |
| -------------------------- | ---------- |
| Warmup | 5 minutes |
| Exercise 1 | 10 minutes |
| Exercise 2 | 10 minutes |
| Intro to technical writing | 45 minutes |
| Exercise 3 | 10 minutes |
| Wrap up | 5 minutes |

# Warmup

* What was the most confusing name you ever encountered?
* Type in the meeting chat
- What was the most confusing name you ever encountered?
- Type in the meeting chat

# Exercise 1

* Prompt
* Discuss a possible meaning of a variable given its name
* Time limit: 10 minutes
- Prompt
- Discuss a possible meaning of a variable given its name
- Time limit: 10 minutes

# Possible answers

| Name | Kind | Meaning |
|---------------------|----------|----------------------------------------------|
| ------------------- | -------- | -------------------------------------------- |
| `is_true` | Function | Check if boolean statement evaluates to true |
| `important_details` | Variable | Details that are important |
| `dataType` | Variable | Contains type of dataset |
Expand All @@ -60,15 +60,15 @@ subtitle: Names++

# Exercise 2

* Prompt
* Fill-in the blanks for using different parts of speech in names
* Parts of speech [reference](https://en.wikipedia.org/wiki/Part_of_speech)
* Time limit: 10 minutes
- Prompt
- Fill-in the blanks for using different parts of speech in names
- Parts of speech [reference](https://en.wikipedia.org/wiki/Part_of_speech)
- Time limit: 10 minutes

# Possible answers

| Entity | Part of speech | Example |
|--------------------------------------------|----------------|--------------------------|
| ------------------------------------------ | -------------- | ------------------------ |
| Class | Noun | `Solver`, `SupplyChain` |
| Variable | Noun | `transaction`, `table` |
| Boolean variable | Predicate | `is_active`, `is_valid` |
Expand All @@ -81,92 +81,92 @@ subtitle: Names++

# Putting parts of speech together

* Write in active voice
* Choose strong verbs
* Reduce the use of _there is_ and _there are_
* Minimize certain adjectives
* Keep list items parallel
- Write in active voice
- Choose strong verbs
- Reduce the use of _there is_ and _there are_
- Minimize certain adjectives
- Keep list items parallel

See [Google Technical Writing](https://developers.google.com/tech-writing/one)
for more details

# Write in active voice

* Use the active voice most of the time
* Most readers mentally translate passive voice to active voice
* It is easier to read
* It is more concise
* Active voice sentence structure
* Active voice sentence = actor + verb + target
* Passive voice sentence = target + verb + actor
* Yoda speak = verb + target + actor
* Examples
* Active voice
* The user clicks the button.
* The system sends the email.
* Passive voice
* The button is clicked by the user.
* The email is sent by the system.
* Yoda speak
* Clicked the button is by the user.
* Sent the email is by the system.
- Use the active voice most of the time
- Most readers mentally translate passive voice to active voice
- It is easier to read
- It is more concise
- Active voice sentence structure
- Active voice sentence = actor + verb + target
- Passive voice sentence = target + verb + actor
- Yoda speak = verb + target + actor
- Examples
- Active voice
- The user clicks the button.
- The system sends the email.
- Passive voice
- The button is clicked by the user.
- The email is sent by the system.
- Yoda speak
- Clicked the button is by the user.
- Sent the email is by the system.

# Choose strong verbs

* Reduce imprecise, weak, or generic verbs, such as the following
* forms of be: is, are, was, were, be, being, been
* occur, happen, take place, come about, come to pass
- Reduce imprecise, weak, or generic verbs, such as the following
- Forms of be: is, are, was, were, be, being, been
- Occur, happen, take place, come about, come to pass

| Weak verb | Strong verb |
|---------------------------------------------|-------------------------------------------------|
| ------------------------------------------- | ----------------------------------------------- |
| The exception occurs when dividing by zero. | Dividing by zero raises the exception. |
| This error message happens when... | The system generates this error message when... |
| We are very careful to ensure... | We carefully ensure... |

# Reduce the use of _there is_ and _there are_

* Remove unnecessary references
* If possible, delete _there is_ and _there are_
* Repair the sentence by moving the true subject and true verb
* Replace _there is_ and _there are_ with a more specific noun or pronoun
- Remove unnecessary references
- If possible, delete _there is_ and _there are_
- Repair the sentence by moving the true subject and true verb
- Replace _there is_ and _there are_ with a more specific noun or pronoun

| Original | Revised |
|-----------------------------------------------------|-----------------------------------------|
| --------------------------------------------------- | --------------------------------------- |
| There is a problem with the system. | The system has a problem. |
| There are no errors in the system. | The system has no errors. |
| There is a function `distribute` that assigns keys. | The `distribute` function assigns keys. |

# Minimize certain adjectives

* Provide facts instead of loosely defined adjectives and adverbs
* Adjectives and adverbs are often vague and imprecise
* Can make the reader wonder what the writer really means
* Example
* Original: Setting this flag makes the application run screamingly fast.
* Revised: Setting this flag makes the application run 150% faster.
- Provide facts instead of loosely defined adjectives and adverbs
- Adjectives and adverbs are often vague and imprecise
- Can make the reader wonder what the writer really means
- Example
- Original: Setting this flag makes the application run screamingly fast.
- Revised: Setting this flag makes the application run 150% faster.

# Write effective lists

* Keep list items parallel
* All items in a list should "belong" together
* Align all items using similar
* grammar and parts of speech
* logical category
* capitalization
* punctuation
* Example of an ineffective list
* Parts of speech -- choose well;
* logical category is essential,
* capitalization and punctuation
- Keep list items parallel
- All items in a list should "belong" together
- Align all items using similar
- Grammar and parts of speech
- Logical category
- Capitalization
- Punctuation
- Example of an ineffective list
- Parts of speech -- choose well;
- Logical category is essential,
- Capitalization and punctuation

# Exercise 3

* Improve the following sentences
- Improve the following sentences
1. The moth was removed by Grace Hopper.
2. Performance optimization is overridden by the `--noperf` flag
3. The measurements were taken by the static `Timer()` method until it
was discovered by the QA team the bugs were present in the `Timer()` method.
* Time limit: 10 minutes
- Time limit: 10 minutes

# Possible answers

Expand All @@ -177,17 +177,17 @@ for more details

# Wrap up

* Choose your names thoughtfully
* Communicate your intent
* Avoid disinformation
* Use pronounceable names
* Avoid encodings
* Choose parts of speech well
* Use The Scope Rule
- Choose your names thoughtfully
- Communicate your intent
- Avoid disinformation
- Use pronounceable names
- Avoid encodings
- Choose parts of speech well
- Use The Scope Rule

# What is next?

* Expect an e-mail with instructions for upcoming coding dojo
- Expect an e-mail with instructions for upcoming coding dojo

# Final words

Expand Down
4 changes: 2 additions & 2 deletions fundamentals/04-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ subtitle: Functions
# Safe refactoring

- **Refactoring** is a process of
- restructuring existing code
- without changing its external behavior
- Restructuring existing code
- Without changing its external behavior
- Safe refactoring
- Put the system under a test
- Run tests often
Expand Down
8 changes: 4 additions & 4 deletions fundamentals/06-function-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ subtitle: Function Structure
- Avoid "output" arguments
- Avoid passing boolean values and null
- Limit the use of switch statements to top-level factory functions
- Limit the interdependencies by using the principle of the least knowledge
- Limit the inter-dependencies by using the principle of the least knowledge
- "Pass a block" to solve the temporal coupling problem
- Use early returns to reduce the nesting level
- Avoid breaks/returns in a middle of a loop
Expand Down Expand Up @@ -127,7 +127,7 @@ subtitle: Function Structure
- Avoid passing boolean values and null
- Reduce coupling
- Limit the use of switch statements to top-level factory functions
- Limit the interdependencies by using the principle of the least knowledge
- Limit the inter-dependencies by using the principle of the least knowledge
- "Pass a block" to solve the temporal coupling problem
- Clarify control flow
- Use early returns to reduce the nesting level
Expand Down Expand Up @@ -161,12 +161,12 @@ subtitle: Function Structure
# Summary

- Simplify function signature
- Function signature should be small - 3 or less arguments
- Function signature should be small -- 3 or less arguments
- Avoid "output" arguments
- Avoid passing boolean values and null
- Reduce coupling
- Limit the use of switch statements to top-level factory functions
- Limit the interdependencies by using the principle of the least knowledge
- Limit the inter-dependencies by using the principle of the least knowledge
- "Pass a block" to solve the temporal coupling problem
- Clarify control flow
- Use early returns to reduce the nesting level
Expand Down
Loading