From feafa6e020ad0a7d0d2331ca2a1a806262c86eba Mon Sep 17 00:00:00 2001 From: Andrey Miroshnikov Date: Fri, 10 Nov 2023 18:57:13 +0000 Subject: [PATCH] Adding LSP and POLA/S to HDL workflow --- HDL_workflow.mdwn | 65 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn index d9e570ba4..0d42fe402 100644 --- a/HDL_workflow.mdwn +++ b/HDL_workflow.mdwn @@ -1163,6 +1163,71 @@ Simply mark it with an appropriate preferably with a link to a URL in the [bugtracker](https://bugs.libre-soc.org/) with further details as to why the unit test should not be run. +## Liskov Substitution Principle + +* [Wikipedia entry](https://en.wikipedia.org/wiki/Liskov_substitution_principle) +* [Stackoverflow answer on LSP](https://stackoverflow.com/questions/56860/what-is-an-example-of-the-liskov-substitution-principle) +* [Article on LSP](https://reflectoring.io/lsp-explained/) + +Copying from Wikipedia: + +``` +The Liskov substitution principle (LSP) is a particular definition of a +subtyping relation, called strong behavioral subtyping, that was initially +introduced by Barbara Liskov in a 1987 conference keynote address titled +Data abstraction and hierarchy. It is based on the concept of +"substitutability" - a principle in object-oriented programming stating +that an object (such as a class) may be replaced by a sub-object (such as +a class that extends the first class) without breaking the program. +It is a semantic rather than merely syntactic relation, because it intends +to guarantee semantic interoperability of types in a hierarchy, object +types in particular. +``` + +To paraphrase: an *original object/class may be replaced with another object* +(whose class extends the first class) *without breaking* the program. + +Python is a programming language which makes using LSP pretty straightforward. + +In LibreSOC, we aim to follow this principle whenever possible and (bearing +time and budget constraints). + +*(Luke, please include some examples from LibreSOC source here)* + +## Principle of Least Astonishment/Surprise (POLA) + +* Example shown by Luke on +[comment #33 bug #1039](https://bugs.libre-soc.org/show_bug.cgi?id=1039#c33) +* [Wikipedia entry](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) +* Example answer on +[software eng. stack exchange](https://softwareengineering.stackexchange.com/questions/187457/what-is-the-principle-of-least-astonishment) + +Wikipedia mentions that the origin of the term "Principle of Least +Astonishment" (or Surprise) comes from a PL/I programming language bulletin +board from 1957: + +``` +For those parts of the system which cannot be adjusted to the peculiarities +of the user, the designers of a systems programming language should obey +the "Law of Least Astonishment." In short, this law states that every construct +in the system should behave exactly as its syntax suggests. Widely accepted +conventions should be followed whenever possible, and exceptions to previously +established rules of the language should be minimal. +``` + +If a method name has a prefix `test_` it should be a unit test (or some other +test which is there to check the functionality of a given feature). + +A method/function (or attributes/variables, etc.) *shouldn't* be given a name +which is wildly different from the what the user would expect it to do. + +*Andrey*: One example which may meet this rule is `TestIssuer`, +which is the FSM-based nMigen HDL CPU core used by LibreSOC (so far). +It is so called because it is used to issue unit tests (while also +being synthesisable). This name was however was initially confusing +to me, because my background is in hardware not software engineering. + + # Task management guidelines 1. Create the task in appropriate "Product" section with appropriate -- 2.30.2