Add architecture properties to implementation guidelines - #103
Conversation
Gazprea gains six inspected properties alongside the existing pass list; VCalc gains a note on which of its assumptions do not survive the transition. Also fixes a missing word in both pass-list bullets and an unindented paragraph under Software Engineering Process that warned on build.
|
This document will need to be rewritten anyway when we change the grading matrix, but I'd like to know what you think of these as an architectural rubric for gazprea. |
|
This is an awesome start! I would like to go over it together so I can understand your motivation and rationale. |
Sir-NoChill
left a comment
Sir-NoChill
left a comment
There was a problem hiding this comment.
I like this as well. We might want to ask around the lab allumni for what their jobs are asking for in terms of code quality as well. Maybe put out the question to nelson and see if he can get in touch with our AMD- and NVIDIA-employed alumni.
| * Your passes must satisfy the following properties. These are assessed by inspection, and carry more weight than the presence of the passes themselves. | ||
|
|
||
| * **Types are decided once.** Your emission pass must not compute or infer the type of an expression. It reads type information recorded by an earlier pass. | ||
|
|
||
| * **One source of truth for conversions.** The rules deciding whether a conversion is legal and the code emitting that conversion must not be two lists kept in agreement by hand. If they are separate, something in your build must check that they agree. | ||
|
|
||
| * **Pass dependencies are written down.** Each pass must state what it requires to already be true when it runs. If reordering two of your passes breaks your compiler, that dependency must appear somewhere a reader can find it. | ||
|
|
||
| * **Element-wise operations share their emission.** Adding a new operator over vectors or matrices must not require writing new index arithmetic. | ||
|
|
||
| * **Names are resolved once.** Your emission pass must not look a name up by string. Symbol resolution happens in an earlier pass, and later passes use the resolved symbol. | ||
|
|
||
| * **Locations are recorded at construction.** Every node carries the source location it came from, assigned when the node is built. | ||
|
|
There was a problem hiding this comment.
Have we given you access to historical gazprea repos? If not I think something useful may be to run a claude over the rest of the gazprea repos to see where each of them did well or maybe made subpar design decisions. I think this is a good start, and I like having this as explicit markable criteria.
| files. | ||
| * Your code should be clean and readable. | ||
| * There is no minimum expectation for commenting or documentation. | ||
| * There is no minimum expectation for commenting or documentation, except where the implementation guidelines require a design decision to be recorded. |
There was a problem hiding this comment.
Maybe there should be? One thing I found useful was doc comments for major methods, and I know this has become a matter of 🤖 taste 🤖 but I think it might be important to discuss how the new bot-driven development paradigm might benefit from better code documentation (but not too much!)
There was a problem hiding this comment.
Since the Parsing assignment will not have interviews, I am thinking that the students will have to explain their design. There are two things I think could be marked: the grammar and the AST design. I think I found that any old grammar can work, but writing a good grammar makes the parsing easier. Same for the AST - a bad one makes it awkward to get a working interpreter.
3 participants
Gazprea gains six inspected properties alongside the existing pass list; VCalc gains a note on which of its assumptions do not survive the transition.
Also fixes a missing word in both pass-list bullets and an unindented paragraph under Software Engineering Process that warned on build.