Skip to content

Commit

Permalink
Adds videos to construction chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
nickbradley committed Aug 1, 2024
1 parent 509c181 commit 2f8f174
Show file tree
Hide file tree
Showing 5 changed files with 37 additions and 10 deletions.
2 changes: 2 additions & 0 deletions reader/content/construction/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ title: "Software Construction"
weight: 6
---

{{< youtube z-Q2CIfshcw >}}

In this chapter, we explore three key aspects of constructing robust and maintainable code:
1. Refactoring: Enhancing code quality by systematically improving existing code without altering its external behavior.
2. Automation: Streamlining repetitive tasks through build automation, continuous integration (CI), and scripting. Automated pipelines ensure consistent, error-free processes.
Expand Down
2 changes: 2 additions & 0 deletions reader/content/construction/automation/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: "Automation"
weight: 4
---

{{< youtube HMtyshK3LNU >}}

Our expectations for modern software systems demand delivering a level of velocity that was not possible in the past. Gone are the days when delivering once every 3-5 years was considered acceptable. Being able to deliver changes on a weekly, daily, or minute-by-minute basis allows software teams to more quickly deliver new products to market or provide more timely bug fixes.

The figure below shows a coarse-grained view of the broad steps required to get a code change deployed in front of a user. While human intervention is required to make every code change, it should be possible to automatically transition from the change in front of a user. The less time this sequence of actions takes (aka the less friction there is in the build process), the quicker the developer can get feedback to refine or roll back their change. Also, the quicker and easier this process is, the more likely developers are to take advantage of it (e.g., if running tests is hard, developers will try not to run them or if deploying is hard developers will avoid deploying fixes that could benefit users unless they are significant 'enough').
Expand Down
4 changes: 4 additions & 0 deletions reader/content/construction/languages/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,10 @@ TODO: This should be added next year
--->


## Static Analysis and Linters

{{< youtube QKK9XAdleFg >}}

## References

* Gerald Sussman's [role of programming](https://www.youtube.com/watch?v=arMH5GjBwUQ) talk.
Expand Down
8 changes: 8 additions & 0 deletions reader/content/construction/refactoring/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: "Refactoring"
weight: 3
---

{{< youtube bHKyMxvZFXY >}}

Refactoring is the process of improving on the implementation of an existing design by restructuring the source code to alleviate existing shortcomings and ease future development. Conceptually, refactoring tasks do not change the semantics of the program (e.g., add new features or fix defects) but instead make the code more amenable to future feature additions and defect fixes. Most refactoring operations consolidate duplicate code, reduce coupling, move elements to make them more cohesive, or otherwise improve the understandability and maintainability of the system. Refactoring is one mechanism used to handle emergent design: as a system evolves, we learn more about what kinds of abstractions are most appropriate. Through refactoring we can incorporate these emergent abstractions into a system's design.

Development teams often think of refactorings as a mechanism for paying technical debt. Technical debt is a metaphor for thinking about how development decisions can influence the long-term viability of a software system. The technical debt metaphor acknowledges that while quick and cheap solutions are often attractive (and the right thing to do), they accrue debt in the overall maintainability of the system by degrading or obfuscating the original design. Technical debt often triggers developers to think about refactoring in one of three main situations:
Expand Down Expand Up @@ -113,8 +115,14 @@ class CourseParser implements IParser {
}
```

## Code Readability
{{< youtube TZ7mfKJa7Sw >}}


## Code smells

{{< youtube oqqaDaQ3m24 >}}

In order to be useful, software must:

* Accomplish its purpose.
Expand Down
31 changes: 21 additions & 10 deletions reader/content/construction/rest/_index.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,23 @@
---
title: "REST"
title: "REST Architecture"
weight: 5
---

[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) is an architectural style heavily used in web-based systems for providing services between different systems (and interfaces). REST defines a means of connecting systems together that focuses on their interfaces rather than their implementations using self-descriptive messages. In this way, REST provides a language to define a specific kind of [APIs](API.md) for communicating across a network. REST services are transported over the network using the [HTTP protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol).

{{< figure src="REST_network.png" alt="REST topology" >}}
{{< youtube Y8AYxFgwmJk >}}

REST services define their resources using uniform resource identifiers (URIs). URIs differ from URLs in that a URI does not define its network location and access mechanism (e.g., ```/dataset``` is a URI while ```http://foo.com/dataset``` is a URL).
[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) is an architectural style heavily used in web-based systems for providing services between different systems (and interfaces). REST defines a means of connecting systems together that focuses on their interfaces rather than their implementations using self-descriptive messages. In this way, REST provides a language to define a specific kind of [APIs]({{% ref "apis" %}}) for communicating across a network. REST services are transported over the network using the [HTTP protocol](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol).

Additional data can be sent to a REST endpoint in the form of HTTP headers or in the HTTP body. It is idiomatic for headers to not contain any information about the location of the resource (this should be in the URI) or to carry any data about the request (this should be in the body); headers are mainly for sending metadata (e.g., to request the response data format or encoding or to provide authorization credentials).
{{< figure src="REST_network.png" alt="REST topology" width="350px" >}}


## Nouns and Verbs

{{< youtube Aoms-MrqW3g >}}

REST services define their resources, as nouns, using uniform resource identifiers (URIs). URIs differ from URLs in that a URI does not define its network location and access mechanism (e.g., ```/dataset``` is a URI while ```http://foo.com/dataset``` is a URL).

## Verbs
Additional data can be sent to a REST endpoint in the form of HTTP headers or in the HTTP body. It is idiomatic for headers to not contain any information about the location of the resource (this should be in the URI) or to carry any data about the request (this should be in the body); headers are mainly for sending metadata (e.g., to request the response data format or encoding or to provide authorization credentials).

REST describes how HTTP verbs should be used when communicating with REST services. REST services respond with payloads (typically JSON or XML) and an integer-based response code. Each REST request uses only one verb and receives only one response.

Expand All @@ -25,7 +31,7 @@ REST describes how HTTP verbs should be used when communicating with REST servic

* ```PATCH``` Used to modify (not completely replace or delete) a resource. Not idempotent. This is the least-frequently used verb. Typical response codes are 200 (ok), 204 (no content), 404 (not found).

A simple set of [quick tips](http://www.restapitutorial.com/lessons/restquicktips.html) and [http status codes](httpstatuses.com) can be helpful for your reference.
A simple set of [quick tips](http://www.restapitutorial.com/lessons/restquicktips.html) and [http status codes](https://httpstatuses.com) can be helpful for your reference.

REST services almost universally respond to requests with XML or JSON requests. XML documents are more verbose, harder to read and write by hand, and are more difficult to parse.

Expand Down Expand Up @@ -62,15 +68,20 @@ The pushback against XML can be more clearly understood when looking at a SOAP e

## Statelessness

{{< youtube JiojH8HfUps >}}

REST services are often viewed as highly scalable. The main reason for this is that there is an expectation that the client maintains state instead of the server. This means that a client can interact with several different servers for a single set of requests (e.g., if one server gets overloaded requests can be transparently migrated).

As a concrete example, if a client is trying to undertake a complex multi-step operation, it is the client's responsibility to keep track of where they are, not the server's responsibility.

Servers are responsible for sending back detailed information about the resources they are returning so that clients have the ability to make further requests of the server with the correct URIs. For example, while could might expect the GitHub ```POST /user/:repo``` endpoint to simply return ```{success: true}``` if a repository was successfully created, it instead returns a wide variety of information that can be used by the user to construct any subsequent requests:
Servers are responsible for sending back detailed information about the resources they are returning so that clients have the ability to make further requests of the server with the correct URIs. For example, while you might expect the GitHub ```POST /user/:repo``` endpoint to simply return ```{success: true}``` if a repository was successfully created, it instead returns a wide variety of information that can be used by the user to construct any subsequent requests:

```json
```plaintext {title="Response Header"}
Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World
```

```json {title="Response Body"}
{
"id": 1296269,
"owner": {
Expand Down Expand Up @@ -173,7 +184,7 @@ The first is that the API must provide a _valuable_ service. Without this value,

APIs should also be sufficiently _flexible_ to work in a wide variety of circumstances. This might mean providing multiple data formats, supporting different protocols, or versions. Additionally, enabling batch or update operations can also ease common developer tasks that might otherwise be hard to perform. This often involves considering the bootstrap process and how long it takes a developer from visiting an API document to successfully making a query (often referred to as the time-to-hello-world).

Effectively _measuring_ your APIs is also important for understanding how your customers are using your system. When an API is servicing hundreds of thousands of requests per day, it is important to understand how your endpoints are being used and how they are generating errors. These measurements are useful both to the API developer to monitor the API, but also for API clients so they can check on the API if they are having any difficulties. Many API platforms have status pages where you can check how the [platform](https://api.twitterstat.us/) [is](https://status.stripe.com/) [performing](https://status.github.com/).
Effectively _measuring_ your APIs is also important for understanding how your customers are using your system. When an API is servicing hundreds of thousands of requests per day, it is important to understand how your endpoints are being used and how they are generating errors. These measurements are useful both to the API developer to monitor the API, but also for API clients, so they can check on the API if they are having any difficulties. Many API platforms have status pages where you can check how the [platform](https://api.twitterstat.us/) [is](https://status.stripe.com/) [performing](https://status.github.com/).

Finally, effective API _documentation_ is key for helping developers understand how to use any API. These documents should clearly describe what the API does, what parameters it expects, and the structure of its return document. Concrete examples showing how the API can be used are also extremely helpful in this context. Many [great](https://developer.github.com/v3/) [examples](https://strava.github.io/api/) can be found online demonstrating effective REST API documentation.

Expand Down

0 comments on commit 2f8f174

Please sign in to comment.