You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: slides/depc/depc5/index.qmd
+38-7Lines changed: 38 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "Project Critique for `Pyrefly`"
3
3
description: "Evaluating a project's documentation"
4
-
date: "2025-12-03"
4
+
date: "2025-12-01"
5
5
date-format: long
6
6
author: V Rieger, Brandon Thompson
7
7
execute:
@@ -19,46 +19,77 @@ format:
19
19
---
20
20
21
21
## Overview of Pyrefly
22
-
Pyrefly is a tool used mainly for type checking. Type checking is making sure that data, such as variables, are the types that they need to be. When using variables, some languages require you to specify a variables type when declaring it, like with Java. This is called a `statically typed language`. Python, however, does not require this specification, as it is a `dynamically typed language`. Dynamically typed languages have type checking occur at runtime.
22
+
23
+
Pyrefly is a tool used mainly for type checking. Type checking is making sure
24
+
that data, such as variables, are the types that they need to be. When using
25
+
variables, some languages require you to specify a variables type when declaring
26
+
it, like with Java. This is called a `statically typed language`. Python,
27
+
however, does not require this specification, as it is a `dynamically typed
28
+
language`. Dynamically typed languages have type checking occur at runtime.
23
29
24
30
## Overview of Pyrefly
25
-
Pyrefly is a way to catch errors before that happens. By using any type annotations that you may have set for a variable, it can tell you when you are assigning a value that doesn’t align with that. For example: declaring a variable as a string with a type annotation then trying to update it with an integer value will have Pyrefly flag that update to let you know there is a problem. This tool not only allows you to catch issues earlier as it works during development rather than having to wait to catch the error in runtime, but it also makes your code more readable by encouraging use of type annotations so you know more about a variable or function.
31
+
32
+
Pyrefly is a way to catch errors before that happens. By using any type
33
+
annotations that you may have set for a variable, it can tell you when you are
34
+
assigning a value that doesn’t align with that. For example: declaring a
35
+
variable as a string with a type annotation then trying to update it with an
36
+
integer value will have Pyrefly flag that update to let you know there is a
37
+
problem. This tool not only allows you to catch issues earlier as it works
38
+
during development rather than having to wait to catch the error in runtime, but
39
+
it also makes your code more readable by encouraging use of type annotations so
40
+
you know more about a variable or function.
26
41
27
42
## Overview of Pyrefly
28
-
Pyrefly also acts as a language server which provides “language-specific features” to a code editor or IDE. Some of the features it provides include go to definition and find references. The former will allow you to click on where a function or class, for example, and bring you to where you defined it, and the latter does the reverse by allowing you to click on a definition and go to all of its uses.
43
+
44
+
Pyrefly also acts as a language server which provides “language-specific
45
+
features” to a code editor or IDE. Some of the features it provides include go
46
+
to definition and find references. The former will allow you to click on where a
47
+
function or class, for example, and bring you to where you defined it, and the
48
+
latter does the reverse by allowing you to click on a definition and go to all
49
+
of its uses.
29
50
30
51
## Overview of Pyrefly's Documentation
52
+
31
53
- Covers what Pyrefly is and why type checking matters
32
54
- Includes guides for installation, configuration, and installation
33
55
- Includes sections for IDE setup, CLI commands, and FAQs
34
56
- Provides examples showing how Pyrefly finds type errors
35
57
36
58
## Strengths of Pyrefly's Documentation
59
+
37
60
- Very clear and well organized
38
61
- Has beginner and advanced topics
39
62
- Good code examples
40
63
- Easy to follow steps for setup
41
64
- Is very transparent about its limitations due to it being in beta
42
65
43
66
## Weaknesses of Pyrefly's Documentation
67
+
44
68
- Some sections lack deep detail
45
69
- Not many real-world examples or complex use cases
46
70
- Lacks guidance for troubleshooting
47
71
- Some features are still marked as unstable due to it being in beta
48
72
49
73
## Relation to Diataxis
74
+
50
75
Pyrefly's documentation includes:
51
76
52
77
- A section for learning about python typing - tutorial
53
78
- Installation and configuration guides - how-to guide
54
79
- A list of features - reference
55
80
56
-
The documentation could, however, include more explanations, further breaking down some of the information.
81
+
The documentation could, however, include more explanations, further breaking
82
+
down some of the information.
57
83
58
84
## Relation to Literate Programming
59
-
Literate programming is about documenting your code to make it more human readable. Pyrefly does this by encouraging use of type annotations in your code. Having these type annotations can give you more information about your variables, functions, classes, etc. which makes them easier to understand.
85
+
86
+
Literate programming is about documenting your code to make it more human
87
+
readable. Pyrefly does this by encouraging use of type annotations in your code.
88
+
Having these type annotations can give you more information about your
89
+
variables, functions, classes, etc. which makes them easier to understand.
60
90
61
91
## Suggestions for improvement
92
+
62
93
- Add real-world examples and more complex use cases
63
94
- Create a troubleshooting section
64
-
- Add Guidance for compatability for popular libraries
95
+
- Add Guidance for compatability for popular libraries
0 commit comments