Code standards update

This commit is contained in:
Kat R. 2022-10-29 09:57:17 -05:00
parent 247f84d906
commit 1ecf3968bc

View file

@ -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").