From 8646d5c4eea43b73ef60cfc6511327a563c38e7f Mon Sep 17 00:00:00 2001 From: DTB Date: Thu, 8 Aug 2024 02:31:54 -0600 Subject: [PATCH 1/6] STYLE: make rules more granular and consistent, add examples --- STYLE | 185 ++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 122 insertions(+), 63 deletions(-) diff --git a/STYLE b/STYLE index 5322661..aa233a2 100644 --- a/STYLE +++ b/STYLE @@ -1,11 +1,26 @@ The following guidelines are conducive to clear and readable code that is consistent with the style of the rest of the Bonsai Computer System. -0. Braces are mandatory for all control flow. +0. Use: + - a single line for control flow statements short enough to be easily +understood at a glance: -1. Nested indentation should be kept to a minimum. + if !(argc < 0) { usage(program_name); } -2. Empty lines should be placed between different kinds of statements: +This applies to C switch cases, as well. + + switch (value) { /* aligning stuff to make it easier to read is fine */ + case possibility: variable = foo; break; + default: variable = NULL; break; + } + + - as little nested logic as possible (within reason). + - braces in control flow, when their inclusion is left optional by a +programming language (in, for example, C). + + if (condition) { statement; } + + - empty lines between different kinds of statements: int t; @@ -25,56 +40,66 @@ consistent with the style of the rest of the Bonsai Computer System. return io; -3. Each block of code should be indented once more than the keyword which -initiated the block: - - switch (c) { - case 'e': mode |= EQUAL; break; - case 'g': mode |= GREATER; break; - case 'l': mode |= LESS; break; - default: return usage(s); - } - -4. In C, spaces should be placed in control flow statements after the keyword -and before the opening brace: - - for (i = 2; i < argc; ++i) { - -5. If a function, a C control flow statement, or a Rust macro has arguments that -cause the statement to be broken into multiple lines, this should be done by -placing the arguments on a new line inside the parentheses: + - compiler options that yield the most useful warnings, such as -Wpedantic in +a lot of C compilers. Fix the warnings, too. See [0]. + - fixed bounds for loops; see [0]. + - one more level of indentation and one line per argument, when a function +call or statement header is too long to fit on one line: let usage = format!( "Usage: {} [-d delimiter] index command [args...]", argv[0], ); -6. If Rust function arguments or fields are on their own lines, they should -always have a trailing comma: + - one more level of indentation than the keyword that initiated a block. + + if (condition) { + statement; + statement; + } + + - the return value of all non-void functions, or explicitly ignore them (like +casting to void in C): + + if ((a = malloc(sizeof char)) == NULL) { /* handle this error */ + (void)fprintf(stderr, "oh noes!"); /* explicitly ignore this one */ + return EX_OSERR; /* ...because the program is exiting anyway */ + } + +See [0]. + + - the smallest possible scope for data; see [0]. + - (C) comments noting all the symbols and macros used from a header, next to +its include macro: + + #include /* close(2), getopt(3), lseek(2), read(2), write(2), + (space-aligned) * optarg, optind, STDIN_FILENO, STDOUT_FILENO */ + + - (C) one more level of indentation within switch cases. + + switch (value) { + case possibility: + statement; + default: + statement; + } + + - (C) spaces in control flow statements, after the keyword and before the +opening brace: + + for (i = 2; i < argc; ++i) { + + - (Cpp) as little of the preprocessor as possible; see [0]. + - (Rust) a trailing comma on all arguments or fields that are on their own +lines: return Err(EvaluationError { message: format!("{}: Invalid token", i), code: EX_DATAERR, }) -7. If text is on the same line as a brace, spaces should be placed after an -opening curly brace and before a closing one: - - use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - -8. If a control flow statement is short enough to be easily understood in a -glance, it may be placed on a single line: - - if !(argc < 0) { usage(program_name); } - -9. In C, note everything you use from a library in a comment subsequent to its -#include statement: - - #include /* close(2), getopt(3), lseek(2), read(2), write(2), - * optarg, optind, STDIN_FILENO, STDOUT_FILENO */ - -10. In Rust, place extern statements after use statements that include standard -library crates. Group alike statements: + - (Rust) extern statements after use statements that include standard library +crates. Group like statements: use std::fs::Path; @@ -84,40 +109,74 @@ library crates. Group alike statements: use strerror::StrError; use sysexits::{ EX_OSERR, EX_USAGE }; -11. Do not use do while loops in C. + - (Rust) if text is on the same line as a brace, spaces after an opening curly +brace and before a closing one: -12. Adhere to the following rules from the paper The Power of 10: Rules for -Developing Safety-Critical Code [0]: - 1. Avoid complex flow constructs, such as goto and recursion. - 2. All loops must have fixed bounds. This prevents runaway code. - 3. Avoid heap memory allocation. - 4. Restrict functions to the length of a single printed page. + use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - 6. Restrict the scope of data to the smallest possible. - 7. Check the return value of all non-void functions, or cast to void to - indicate the return value is useless (such as in the case of using - fprintf(3p) to print to the standard error). - 8. Use the preprocessor sparingly. - 9. Limit pointer use to a single dereference, and do not use function - pointers. - 10. Compile with all possible warnings active; all warnings should then be - addressed before release of the software (for C compilers, compile with - -Wpedantic). + - (Rust) one more level of indentation within match arms. -13. Remember this quote from The Elements of Programming Style by Brian -Kernighan: - Everyone knows that debugging is twice as hard as writing a program in the - first place. So if you're as clever as you can be when you write it, how - will you ever debug it? +1. Avoid: + - function pointers; see [0]. + - heap memory allocation; see [0]. + - too many levels of dereferences; see [0]. + /* do not do this */ + for (size_t i = 0; i < sizeof a / sizeof *a; ++i) { + if (a[i].id == MATCH) { a[i].val = 0; } + } + + /* do this */ + for (struct MadeUp *s = &a[0]; *s != NULL; s = &s[1]) { + if (s->id == MATCH) { s->val = 0; } + } + +2. Do not use: + - more than the length of one printed page for a function; see [0]. + - recursion, as it's complex and can unexpectedly overflow the stack; see [0] +and section 2 of this document. + - (C) any language features not in C99. + - (C) do-while loops, as they're unique to the language and confusing for +casual C programmers. + - (C) gotos; use sensible flow control, see [0]. + - (C) pointer arithmetic, as it tends to be confusing and unnecessary; use +index-reference patterns like &p[1] instead of p + 1. &p[n] is the address at +p + sizeof p * n, not p + n, like pointer arithmetic suggests. + - (C) struct bitfields in unions, to access certain bits of bigger data types, +as it's poorly defined in the C standards; use bit arithmetic. + - (C) trigraphs. + - (Cpp) inclusions in C header files, to prevent multiple file inclusions. + - (Cpp) variables to prevent multiple inclusions of the same file, such as: + + #ifdef _FILE + #define _FILE + /* file body */ + #endif /* ifdef _FILE */ + +Instead, take the time to ensure other files aren't including the any files +twice. + + - (libc) any functionality not in the latest POSIX or C99. + - (libc) gets(3p) from , as it's impossible to prevent buffer +overflows when it's used; use fgets(3p) from . + - (libc) scanf(3p) from ; see [1]. + - (Make) any functionality not described in make(1p) from the latest POSIX. + +2. Keep the following in mind: + - Everyone knows that debugging is twice as hard as writing a program in the +first place. So if you're as clever as you can be when you write it, how will +you ever debug it? + -- Brian Kernighan, in The Elements of Programming Style References ========== [0] +[1] -- Copyright © 2024 Emma Tebibyte +Copyright © 2024 DTB Copyright © Wikipedia contributors This work is licensed under CC BY-SA 4.0. To view a copy of this license, visit -- 2.46.1 From 4cb5ea78d71e564939d1c5ab464a85bea8de9ba0 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 5 Sep 2024 12:44:14 -0600 Subject: [PATCH 2/6] STYLE: improves clarity, focus, distribution of items, adds more gripes, includes usage text style --- STYLE | 198 +++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 127 insertions(+), 71 deletions(-) diff --git a/STYLE b/STYLE index aa233a2..1aeb1b1 100644 --- a/STYLE +++ b/STYLE @@ -1,26 +1,33 @@ +“Everyone knows that debugging is twice as hard as writing a program in the +first place. So if you’re as clever as you can be when you write it, how +will you ever debug it?” + – Brian Kernighan, The Elements of Programming Style + + The following guidelines are conducive to clear and readable code that is consistent with the style of the rest of the Bonsai Computer System. -0. Use: - - a single line for control flow statements short enough to be easily -understood at a glance: + +Use +=== + + 0. A single line for control flow statements short enough to be easily + understood at a glance: if !(argc < 0) { usage(program_name); } -This applies to C switch cases, as well. + This applies to C switch cases, as well: switch (value) { /* aligning stuff to make it easier to read is fine */ case possibility: variable = foo; break; default: variable = NULL; break; } - - as little nested logic as possible (within reason). - - braces in control flow, when their inclusion is left optional by a -programming language (in, for example, C). + 1. Braces in control flow where their inclusion is left optional in C: if (condition) { statement; } - - empty lines between different kinds of statements: + 2. Empty lines between different kinds of statements: int t; @@ -40,66 +47,59 @@ programming language (in, for example, C). return io; - - compiler options that yield the most useful warnings, such as -Wpedantic in -a lot of C compilers. Fix the warnings, too. See [0]. - - fixed bounds for loops; see [0]. - - one more level of indentation and one line per argument, when a function -call or statement header is too long to fit on one line: + 3. Compiler options that yield the most useful warnings, such as -Wpedantic in + a lot of C compilers. Fix the warnings, too [0]. + + 4. Fixed bounds for loops [0]. + + 5. One more level of indentation and one argument per line when a function + call or statement header is too long to fit on one line: let usage = format!( "Usage: {} [-d delimiter] index command [args...]", argv[0], ); - - one more level of indentation than the keyword that initiated a block. + 6. One more level of indentation than the keyword that initiated a multi-line + block. if (condition) { statement; statement; } - - the return value of all non-void functions, or explicitly ignore them (like -casting to void in C): + 7. The return value of all non-void functions, or explicitly ignore them (like + casting to void in C) [0]: if ((a = malloc(sizeof char)) == NULL) { /* handle this error */ (void)fprintf(stderr, "oh noes!"); /* explicitly ignore this one */ return EX_OSERR; /* ...because the program is exiting anyway */ } -See [0]. + 8. The smallest possible scope for data [0]. - - the smallest possible scope for data; see [0]. - - (C) comments noting all the symbols and macros used from a header, next to -its include macro: + 9. Comments noting all the symbols and macros used from a C header file, next + to its include macro: #include /* close(2), getopt(3), lseek(2), read(2), write(2), (space-aligned) * optarg, optind, STDIN_FILENO, STDOUT_FILENO */ - - (C) one more level of indentation within switch cases. - - switch (value) { - case possibility: - statement; - default: - statement; - } - - - (C) spaces in control flow statements, after the keyword and before the -opening brace: + 10. Spaces in control flow statements, after the keyword and before the + opening brace: for (i = 2; i < argc; ++i) { - - (Cpp) as little of the preprocessor as possible; see [0]. - - (Rust) a trailing comma on all arguments or fields that are on their own -lines: + + 11. In Rust, a trailing comma on all arguments or fields that are on their own + lines: return Err(EvaluationError { message: format!("{}: Invalid token", i), code: EX_DATAERR, }) - - (Rust) extern statements after use statements that include standard library -crates. Group like statements: + 12. In Rust, place extern statements after use statements that include standard + library crates. Group like statements: use std::fs::Path; @@ -109,17 +109,29 @@ crates. Group like statements: use strerror::StrError; use sysexits::{ EX_OSERR, EX_USAGE }; - - (Rust) if text is on the same line as a brace, spaces after an opening curly -brace and before a closing one: + 13. If text is on the same line as a brace, spaces after an opening brace and + before a closing one: use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - - (Rust) one more level of indentation within match arms. + 14. One more level of indentation for match arms and switch cases. -1. Avoid: - - function pointers; see [0]. - - heap memory allocation; see [0]. - - too many levels of dereferences; see [0]. + 15. Alphabetic sorting, where applicable: + + use std::io::{ BufWriter, Read, Write, stderr, stdin, stdout } + + 16. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) + and the to_string() method on other types. + + +Avoid +===== + + 0. Heap memory allocation [0]. + + 1. Using too much nested logic (within reason). + + 2. Too many levels of dereferences [0]: /* do not do this */ for (size_t i = 0; i < sizeof a / sizeof *a; ++i) { @@ -131,48 +143,92 @@ brace and before a closing one: if (s->id == MATCH) { s->val = 0; } } -2. Do not use: - - more than the length of one printed page for a function; see [0]. - - recursion, as it's complex and can unexpectedly overflow the stack; see [0] -and section 2 of this document. - - (C) any language features not in C99. - - (C) do-while loops, as they're unique to the language and confusing for -casual C programmers. - - (C) gotos; use sensible flow control, see [0]. - - (C) pointer arithmetic, as it tends to be confusing and unnecessary; use -index-reference patterns like &p[1] instead of p + 1. &p[n] is the address at -p + sizeof p * n, not p + n, like pointer arithmetic suggests. - - (C) struct bitfields in unions, to access certain bits of bigger data types, -as it's poorly defined in the C standards; use bit arithmetic. - - (C) trigraphs. - - (Cpp) inclusions in C header files, to prevent multiple file inclusions. - - (Cpp) variables to prevent multiple inclusions of the same file, such as: + 3. Using C preprocessor macros; the fewer, the better [0]. + + 4. The exit(3p) and std::process::exit() functions; returning from the main + function skips a system call. + + +Do Not Use +========== + + 0. Function pointers [0]. + + 1. More than the length of one printed page for a function [0]. + + 2. Recursion, as it’s complex and can unexpectedly overflow the stack [0]. + + 3. Any functionality not in the POSIX C specification and language features not + in C99. + + 4. Do-while loops, as they’re unique to C and confusing for casual programmers. + + 5. Labels and goto statements; use sensible flow control [0]. + + 6. Pointer arithmetic, as it tends to be confusing and unnecessary; use + index-reference patterns like &p[1] instead of p + 1. &p[n] is the address at + p + sizeof p * n, not p + n, like pointer arithmetic suggests. + + 7. C struct bitfields in unions, to access certain bits of bigger data types, + as it’s poorly defined in the C standards; use bit arithmetic. + + 8. C trigraphs. + + 9. Inclusions in C header files, to prevent multiple file inclusions. + + 10. C preprocessor variables to prevent multiple inclusions of the same file, + such as: #ifdef _FILE #define _FILE /* file body */ #endif /* ifdef _FILE */ -Instead, take the time to ensure other files aren't including the any files -twice. + Instead, take the time to ensure other files aren’t including the any files + twice. - - (libc) any functionality not in the latest POSIX or C99. - - (libc) gets(3p) from , as it's impossible to prevent buffer -overflows when it's used; use fgets(3p) from . - - (libc) scanf(3p) from ; see [1]. - - (Make) any functionality not described in make(1p) from the latest POSIX. + 11. The gets(3p) function from , as it’s impossible to prevent buffer + overflows when it's used; use fgets(3p) from . + + 12. The scanf(3p) function from [1]. + + 13. Any functionality not described in the latest POSIX make(1) specification. + + 14. Macros which panic on failure in Rust (such as the print!() and println!() + macros). Use a function and handle any errors. However, do use the eprintln!() + macro for error messages. Handling an error for writing an error message is + redundant. + + +Usage Text +========== + +This section is adapted from the NetBSD style guide [2]. + +When programs are invoked incorrectly and in the synopsis of manual pages, uasge +text should be provided to the user. The following is the format used by this +project for this purpose: + +All optional arguments are to be placed in square brackets (U+005B, U+005D). +Mutually exclusive arguments can be separated by a vertical line (U+007C). +Groups of arguments should be specified in alphabetical order in most cases. The +order of arguments and an example of these rules follows: + + 0. Options with no option arguments. + 1. Options with option arguments. Arguments should be specified inside the same + square brackets as the options. + 3. Non-option arguments. + + "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" + "usage: f [-a | -b] [-c [-de] [-n number]]\n" -2. Keep the following in mind: - - Everyone knows that debugging is twice as hard as writing a program in the -first place. So if you're as clever as you can be when you write it, how will -you ever debug it? - -- Brian Kernighan, in The Elements of Programming Style References ========== [0] [1] +[2] -- Copyright © 2024 Emma Tebibyte -- 2.46.1 From 790b12fb40171847f29872902b6c7995f9f89061 Mon Sep 17 00:00:00 2001 From: emma Date: Thu, 5 Sep 2024 15:55:32 -0600 Subject: [PATCH 3/6] STYLE: changes numbering scheme to transcend headers, fixes minor errors --- STYLE | 68 +++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/STYLE b/STYLE index 1aeb1b1..bb3438f 100644 --- a/STYLE +++ b/STYLE @@ -16,13 +16,28 @@ Use if !(argc < 0) { usage(program_name); } - This applies to C switch cases, as well: + This applies to C switch statements and cases and Rust match statements, as + well: switch (value) { /* aligning stuff to make it easier to read is fine */ case possibility: variable = foo; break; default: variable = NULL; break; } + switch (value) { + case possibility: + statement; + break; + case default: + statement; + break; + } + + match result { + Ok(n) => variable = n, + Err(e) => error = e, + } + 1. Braces in control flow where their inclusion is left optional in C: if (condition) { statement; } @@ -114,24 +129,24 @@ Use use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - 14. One more level of indentation for match arms and switch cases. - - 15. Alphabetic sorting, where applicable: + 14. Alphabetic sorting, where applicable: use std::io::{ BufWriter, Read, Write, stderr, stdin, stdout } - 16. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) + 15. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) and the to_string() method on other types. Avoid ===== - 0. Heap memory allocation [0]. + 16. Function pointers [0]. - 1. Using too much nested logic (within reason). + 17. Heap memory allocation [0]. - 2. Too many levels of dereferences [0]: + 19. Using too much nested logic (within reason). + + 20. Too many levels of dereferences [0]: /* do not do this */ for (size_t i = 0; i < sizeof a / sizeof *a; ++i) { @@ -143,40 +158,38 @@ Avoid if (s->id == MATCH) { s->val = 0; } } - 3. Using C preprocessor macros; the fewer, the better [0]. + 21. Using C preprocessor macros; the fewer, the better [0]. - 4. The exit(3p) and std::process::exit() functions; returning from the main + 22. The exit(3p) and std::process::exit() functions; returning from the main function skips a system call. Do Not Use ========== - 0. Function pointers [0]. + 23. More than the length of one printed page for a function [0]. - 1. More than the length of one printed page for a function [0]. + 24. Recursion, as it’s complex and can unexpectedly overflow the stack [0]. - 2. Recursion, as it’s complex and can unexpectedly overflow the stack [0]. - - 3. Any functionality not in the POSIX C specification and language features not + 25. Any functionality not in the POSIX C specification and language features not in C99. - 4. Do-while loops, as they’re unique to C and confusing for casual programmers. + 26. Do-while loops, as they’re unique to C and confusing for casual programmers. - 5. Labels and goto statements; use sensible flow control [0]. + 27. Labels and goto statements; use sensible flow control [0]. - 6. Pointer arithmetic, as it tends to be confusing and unnecessary; use + 28. Pointer arithmetic, as it tends to be confusing and unnecessary; use index-reference patterns like &p[1] instead of p + 1. &p[n] is the address at p + sizeof p * n, not p + n, like pointer arithmetic suggests. - 7. C struct bitfields in unions, to access certain bits of bigger data types, + 29. C struct bitfields in unions, to access certain bits of bigger data types, as it’s poorly defined in the C standards; use bit arithmetic. - 8. C trigraphs. + 30. C trigraphs. - 9. Inclusions in C header files, to prevent multiple file inclusions. + 31. Inclusions in C header files, to prevent multiple file inclusions. - 10. C preprocessor variables to prevent multiple inclusions of the same file, + 32. C preprocessor variables to prevent multiple inclusions of the same file, such as: #ifdef _FILE @@ -184,17 +197,16 @@ Do Not Use /* file body */ #endif /* ifdef _FILE */ - Instead, take the time to ensure other files aren’t including the any files - twice. + Instead, take the time to ensure other files aren’t including any files twice. - 11. The gets(3p) function from , as it’s impossible to prevent buffer + 33. The gets(3p) function from , as it’s impossible to prevent buffer overflows when it's used; use fgets(3p) from . - 12. The scanf(3p) function from [1]. + 34. The scanf(3p) function from [1]. - 13. Any functionality not described in the latest POSIX make(1) specification. + 35. Any functionality not described in the latest POSIX make(1) specification. - 14. Macros which panic on failure in Rust (such as the print!() and println!() + 36. Macros which panic on failure in Rust (such as the print!() and println!() macros). Use a function and handle any errors. However, do use the eprintln!() macro for error messages. Handling an error for writing an error message is redundant. -- 2.46.1 From f6559b464a72541a14f51434e20996cb222d7539 Mon Sep 17 00:00:00 2001 From: emma Date: Sat, 7 Sep 2024 12:51:18 -0600 Subject: [PATCH 4/6] STYLE: fix minor issues --- STYLE | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/STYLE b/STYLE index bb3438f..a0e6c05 100644 --- a/STYLE +++ b/STYLE @@ -24,6 +24,9 @@ Use default: variable = NULL; break; } + 1. Switch cases in C and match arms in Rust should start another level of + indentation: + switch (value) { case possibility: statement; @@ -38,11 +41,11 @@ Use Err(e) => error = e, } - 1. Braces in control flow where their inclusion is left optional in C: + 2. Braces in control flow where their inclusion is left optional in C: if (condition) { statement; } - 2. Empty lines between different kinds of statements: + 3. Empty lines between different kinds of statements: int t; @@ -62,12 +65,12 @@ Use return io; - 3. Compiler options that yield the most useful warnings, such as -Wpedantic in + 4. Compiler options that yield the most useful warnings, such as -Wpedantic in a lot of C compilers. Fix the warnings, too [0]. - 4. Fixed bounds for loops [0]. + 5. Fixed bounds for loops [0]. - 5. One more level of indentation and one argument per line when a function + 6. One more level of indentation and one argument per line when a function call or statement header is too long to fit on one line: let usage = format!( @@ -75,7 +78,7 @@ Use argv[0], ); - 6. One more level of indentation than the keyword that initiated a multi-line + 7. One more level of indentation than the keyword that initiated a multi-line block. if (condition) { @@ -83,7 +86,7 @@ Use statement; } - 7. The return value of all non-void functions, or explicitly ignore them (like + 8. The return value of all non-void functions, or explicitly ignore them (like casting to void in C) [0]: if ((a = malloc(sizeof char)) == NULL) { /* handle this error */ @@ -91,21 +94,21 @@ Use return EX_OSERR; /* ...because the program is exiting anyway */ } - 8. The smallest possible scope for data [0]. + 9. The smallest possible scope for data [0]. - 9. Comments noting all the symbols and macros used from a C header file, next + 10. Comments noting all the symbols and macros used from a C header file, next to its include macro: #include /* close(2), getopt(3), lseek(2), read(2), write(2), (space-aligned) * optarg, optind, STDIN_FILENO, STDOUT_FILENO */ - 10. Spaces in control flow statements, after the keyword and before the + 11. Spaces in control flow statements, after the keyword and before the opening brace: for (i = 2; i < argc; ++i) { - 11. In Rust, a trailing comma on all arguments or fields that are on their own + 12. In Rust, a trailing comma on all arguments or fields that are on their own lines: return Err(EvaluationError { @@ -113,7 +116,7 @@ Use code: EX_DATAERR, }) - 12. In Rust, place extern statements after use statements that include standard + 13. In Rust, place extern statements after use statements that include standard library crates. Group like statements: use std::fs::Path; @@ -124,25 +127,25 @@ Use use strerror::StrError; use sysexits::{ EX_OSERR, EX_USAGE }; - 13. If text is on the same line as a brace, spaces after an opening brace and + 14. If text is on the same line as a brace, spaces after an opening brace and before a closing one: use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - 14. Alphabetic sorting, where applicable: + 15. Alphabetic sorting, where applicable: use std::io::{ BufWriter, Read, Write, stderr, stdin, stdout } - 15. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) + 16. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) and the to_string() method on other types. Avoid ===== - 16. Function pointers [0]. + 17. Function pointers [0]. - 17. Heap memory allocation [0]. + 18. Heap memory allocation [0]. 19. Using too much nested logic (within reason). -- 2.46.1 From b56a66f9805d62841ed8c851ab8568a4d70dd00f Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 10 Sep 2024 01:59:59 -0600 Subject: [PATCH 5/6] STYLE: fixes default case in example --- STYLE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE b/STYLE index a0e6c05..44d8846 100644 --- a/STYLE +++ b/STYLE @@ -31,7 +31,7 @@ Use case possibility: statement; break; - case default: + default: statement; break; } -- 2.46.1 From f66fdef9c339b7fa303b1e10961fd4ac6f9bd11b Mon Sep 17 00:00:00 2001 From: emma Date: Tue, 10 Sep 2024 02:05:01 -0600 Subject: [PATCH 6/6] STYLE: avoid unbounded loops --- STYLE | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/STYLE b/STYLE index 44d8846..1e6dadb 100644 --- a/STYLE +++ b/STYLE @@ -68,9 +68,7 @@ Use 4. Compiler options that yield the most useful warnings, such as -Wpedantic in a lot of C compilers. Fix the warnings, too [0]. - 5. Fixed bounds for loops [0]. - - 6. One more level of indentation and one argument per line when a function + 5. One more level of indentation and one argument per line when a function call or statement header is too long to fit on one line: let usage = format!( @@ -78,7 +76,7 @@ Use argv[0], ); - 7. One more level of indentation than the keyword that initiated a multi-line + 6. One more level of indentation than the keyword that initiated a multi-line block. if (condition) { @@ -86,7 +84,7 @@ Use statement; } - 8. The return value of all non-void functions, or explicitly ignore them (like + 7. The return value of all non-void functions, or explicitly ignore them (like casting to void in C) [0]: if ((a = malloc(sizeof char)) == NULL) { /* handle this error */ @@ -94,21 +92,21 @@ Use return EX_OSERR; /* ...because the program is exiting anyway */ } - 9. The smallest possible scope for data [0]. + 8. The smallest possible scope for data [0]. - 10. Comments noting all the symbols and macros used from a C header file, next + 9. Comments noting all the symbols and macros used from a C header file, next to its include macro: #include /* close(2), getopt(3), lseek(2), read(2), write(2), (space-aligned) * optarg, optind, STDIN_FILENO, STDOUT_FILENO */ - 11. Spaces in control flow statements, after the keyword and before the + 10. Spaces in control flow statements, after the keyword and before the opening brace: for (i = 2; i < argc; ++i) { - 12. In Rust, a trailing comma on all arguments or fields that are on their own + 11. In Rust, a trailing comma on all arguments or fields that are on their own lines: return Err(EvaluationError { @@ -116,7 +114,7 @@ Use code: EX_DATAERR, }) - 13. In Rust, place extern statements after use statements that include standard + 12. In Rust, place extern statements after use statements that include standard library crates. Group like statements: use std::fs::Path; @@ -127,22 +125,24 @@ Use use strerror::StrError; use sysexits::{ EX_OSERR, EX_USAGE }; - 14. If text is on the same line as a brace, spaces after an opening brace and + 13. If text is on the same line as a brace, spaces after an opening brace and before a closing one: use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; - 15. Alphabetic sorting, where applicable: + 14. Alphabetic sorting, where applicable: use std::io::{ BufWriter, Read, Write, stderr, stdin, stdout } - 16. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) + 15. In Rust, use the to_owned() method on string types (str, OsStr, CStr, etc.) and the to_string() method on other types. Avoid ===== + 16. Unbounded loops [0]. + 17. Function pointers [0]. 18. Heap memory allocation [0]. -- 2.46.1