From 1ecf3968bceb52914239bb75a6bf4f1b793ef205 Mon Sep 17 00:00:00 2001 From: Kat Richey Date: Sat, 29 Oct 2022 09:57:17 -0500 Subject: [PATCH] Code standards update --- notes/notes on code standards and style | 52 +++++++++++++++---------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/notes/notes on code standards and style b/notes/notes on code standards and style index 302130c..c8c5a1a 100644 --- a/notes/notes on code standards and style +++ b/notes/notes on code standards and style @@ -1,3 +1,8 @@ +Before delving in here, do note this is largely guidelines. I'm known to not +follow my own code standards. This is largely just to help keep anyone who wants +to help out on the same page. Ultimately, if you need to break a "rule", break +it. Just make sure you know what you're breaking and why. + Intellectual property ===================== @@ -9,8 +14,9 @@ Regarding free programs: Be careful referencing them, especially if they use a GPL-style license. I don't need that fucking licensing nightmare getting dragged into this. If it -uses a 0BSD-style license, you can freely reference it, even copy it. I just -ask that you properly credit the original. +uses a 0BSD-style license, you can freely reference it. I just ask that you +properly credit the original. Also, try not to straight up copy it. I'm going +for original code here. Trademarks: @@ -44,7 +50,12 @@ or that is otherwise optional, e.g. a game. Non-standard features: Don't use them. For instance, don't use any GNU C extensions. You should be -writing standard compliant code. Specifically, we use `-std=c99`. +writing standard compliant code. Specifically, we use `-std=c99`. This said, +extensions may be unavoidable in places. The packing requirements for i386 +interrupt structs, for instance, seemingly necessitates __attribute__((packed)), +but that may just be a lack of understanding of C structure packing on my part. +Maybe, just maybe, that could be done without. But, yeah. Unless absolutely +necessary, don't use extensions beyond the POSIX extensions. More on C standards: @@ -198,13 +209,6 @@ Start with argv[0]. If it's a path name, it should be basename(argv[0]). That's all I have to say, really. -GUIs: - -We're not really concerned about them at this point in time. When we get to -that, we're gonna probably be running off the X Window System. We'll probably -have our own WM/DE. But, again, we're not worried about that right now. Right -now, we're focused on just getting the console level stuff up. - CLIs: Follow POSIX guidelines for options. I've broken this next rule quite a bit, @@ -230,7 +234,8 @@ File usage: In general, /etc is where configuration for system-level stuff goes. Runtime created files should go in /var/cache or /tmp. You can also use /var/lib. Files may be stored in /usr, but be prepared for a read-only /usr. Don't assume -you can write to /usr. +you can write to /usr. In general, for system scope files (i.e. everything +outside of /home), refer to the filesystem hierarchy. Style and other important things about C ======================================== @@ -280,7 +285,12 @@ line, like so: For indentation, spaces, 2 spaces specifically. And, yeah. Use your brain on how to actually use that. (The exception to this rule is makefiles, which require tabs and a specific indentation style. Look up more on makefiles for -that information.) +that information.) I know that tabs are technically better for accessibility, +but I've already written so much code with 2-space indents, and I really don't +feel like going back and fixing every single file, and I'd like everything to +remain consistent. If you want to replace every single space indent with tabs, +let me know. I'll give you my blessing and we'll use tabs for all new code. +Until then, sorry, I guess. Comments: @@ -312,9 +322,9 @@ feel like you *need* to add them, especially if the function has a sensible name. Like, if they function is called do_x(), you don't need a comment that says that it "Does X". -Please only use one space after a sentence. It'll annoy me otherwise. Also, use -complete sentences, capitalize sentences unless they start with a lowercase -identifier, etc., etc. +Please only use one space after a sentence. It'll annoy me otherwise. Otherwise, +I'm not your English teacher. You're [sic] grammar doesn't need to be perfect, +as long as i [sic] (and others) can tell what you mean. When commenting code, try not to comment the obvious. In general, if you need to have a comment on what a variable does, you need to re-name the variable. @@ -322,6 +332,13 @@ If you need to comment on what a block of code is doing, consider whether it needs to be that complicated or if you can simplify it. This isn't always true, but in general, try to keep to that rule of thumb. +If a variable is supposed to be a command-line flag, maybe include a comment +for what option it's supposed to be (i.e. /* -b */) if the name doesn't make it +otherwise obvious (e.g. the using_unbuffered_output variable in cat.c +corresponding to the -u flag.) If your flags are those kinda octal things +(04 for -x, 02 for -y, 01 for -z), definitely include a comment on what +corresponds to what (/* 04: -x, 02: -y, 01: -z */). + Using C constructs: Always declare the type of objects. Explicitly declare all arguments to @@ -382,11 +399,6 @@ you should try not to. Use underscores to separate words in identifiers (snake_case), not CamelCase. -If a variable is supposed to be a command-line flag, maybe include a comment -for what option it's supposed to be (i.e. /* -b */). If your flags are those -kinda octal things (04 for -x, 02 for -y, 01 for -z), definitely include a -comment on what corresponds to what (/* 04: -x, 02: -y, 01: -z */). - For names with constant values, you can probably decide on your own whether it's better to use an enum or #define. If you use a #define, the name should be in all uppercase ("DEFINE_CONST"). Enums should use lowercase ("enum_const").