Skip to content

Add architecture properties to implementation guidelines #103

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

Open
novo52 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add architecture properties to implementation guidelines #103

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
25 changes: 20 additions & 5 deletions info/grading.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Code Style and Consistency
* You are expected to separate class definitions from implementations using header (.h) and source (.cpp)
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.

@Sir-NoChill Sir-NoChill Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!)

@rcunrau rcunrau Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Software Engineering Process (Gazprea only)
---------------------------------------------------
Expand All @@ -59,8 +59,7 @@ Software Engineering Process (Gazprea only)

* Each team should be ready to present evidence that they adhered to their plan. It is suggested to create a `PLAN.md` (or similarly named) file in the base of your repo. Updating your plan throughout the project is fine so long as it represents an improvement to the process.

* Failure to specify a thorough plan or to adhere to it may result in mark deductions from this category.
Otherwise, this should be an easy 5%. The most successful teams will establish a clear software engineering process even without being explicitly required.
* Failure to specify a thorough plan or to adhere to it may result in mark deductions from this category. Otherwise, this should be an easy 5%. The most successful teams will establish a clear software engineering process even without being explicitly required.

Grammar
---------------------------------------------------
Expand All @@ -83,16 +82,18 @@ Implementation Guidelines Compliance
* **VCalc:**

* You should write your compiler as a series of passes each with simple functionality. Do not implement
your compiler as a single pass. As a minimum, your compiler should individual passes that perform
your compiler as a single pass. As a minimum, your compiler should have individual passes that perform
each of the following actions:

* Create an abstract syntax tree.
* Emit LLVM, SCF, Memref and Arith Dialects that can be lowered into LLVM IR.

* Some VCalc designs do not carry over to Gazprea. Gazprea has multiple scalar types with promotion between them, nested tuple types, matrices and strings alongside vectors, assignable expressions other than plain identifiers, and routines callable before they are defined. A VCalc compiler can reasonably assume a single scalar type, a flat type tag, a one-dimensional vector representation, and one value per expression; none of these assumptions hold in Gazprea. Consider this when choosing how to represent types and values.

* **Gazprea:**

* You should write your compiler as a series of passes each with simple functionality. Do not implement
your compiler as a single pass. As a minimum, your compiler should individual passes that perform
your compiler as a single pass. As a minimum, your compiler should have individual passes that perform
each of the following actions:

* Create an abstract syntax tree.
Expand All @@ -104,6 +105,20 @@ Implementation Guidelines Compliance

* Your compiler should use a symbol table to track symbol definitions and scopes.

* 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.

Comment on lines +108 to +121

@Sir-NoChill Sir-NoChill Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

TA Specification Tests
---------------------------------------------------

Expand Down
Loading