aboutsummaryrefslogtreecommitdiff
path: root/style.md
diff options
context:
space:
mode:
authorlonkaars <loek@pipeframe.xyz>2023-02-24 12:49:20 +0100
committerlonkaars <loek@pipeframe.xyz>2023-02-24 12:49:20 +0100
commit14a1c464c27206bff847fd46d3d5594b30f53af9 (patch)
tree213791289bf22a73eae33c367ccf14636f9822d0 /style.md
parentfd4732181317907d51be645f75d138c2176a8e3b (diff)
update style guide and format code
Diffstat (limited to 'style.md')
-rw-r--r--style.md29
1 files changed, 28 insertions, 1 deletions
diff --git a/style.md b/style.md
index 4a65ed3..3fe912b 100644
--- a/style.md
+++ b/style.md
@@ -30,12 +30,14 @@ before formatting as a failsafe.
- custom typedefs are prefixed with `hh_` and suffixed with `_t` (e.g. `hh_bam_tile_t`)
- library hooks that need specific symbol names are exempt from the naming
conventions (e.g. `main` or `HAL_UART_MspInit`)
+- names are always in English
## others
- document **how to use** code using doxygen-style comments in headers
- document **what code is doing** using inline comments (where applicable)
- don't write redundant comments (e.g. `int c = a + b; // add a and b`)
+- comments are always in English
### markdown
@@ -52,4 +54,29 @@ before formatting as a failsafe.
- vhdl filename is the same as the component name
- vhdl files should end in the `.vhd` file extension, not `.vhdl`
- use spaces around the colon used for setting the type of signal definitions
-
+- do not mix uppercase and lowercase in entity/component/port/signal names
+- remove the default vivado file headers (large comment blocks with file info)
+- add a comment to the entity definition describing what the entity does
+- library import names should be lowercase
+- with the exception of off by one shifts, absolutely NO magic numbers are
+ allowed. use existing constants if possible, or create new ones in a consts
+ file instead of using magic numbers.
+- entities/components without a generic map should put the opening `port (` on
+ the same line as the `entity ... is ` line
+- entities/components with a generic map should be formatted like this:
+ ```
+ entity ... is
+ generic map(
+ NAME : type := default;
+ NAME : type := default)
+ port map(
+ NAME : in type;
+ NAME : out type);
+ end ...;
+ ```
+- port/generic maps with only one signal should be condensed into a single line
+- all library declarations should be grouped together at the top of the file
+- all `use` directives should be grouped together below the library
+ declarations
+- use a space before and after the comment syntax, e.g. `variable x : integer
+ := 0; -- comment here`