From 710ab00dc254f99325c4632c3558e2d7f9e18695 Mon Sep 17 00:00:00 2001 From: Miloslav Ciz Date: Sat, 6 Nov 2021 14:59:13 -0500 Subject: [PATCH] Update shit --- comment.md | 17 +++++++++++++++++ lrs.md | 2 +- modern.md | 3 +++ 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 comment.md create mode 100644 modern.md diff --git a/comment.md b/comment.md new file mode 100644 index 0000000..f0662f0 --- /dev/null +++ b/comment.md @@ -0,0 +1,17 @@ +# Comment + +Comment is part of program's [source code](source_code.md) that doesn't affect the program's behavior in any way (it's invisible to the [compiler](compiler.md)) and mostly serves only to hold information for human programmers (even though it can sometimes contain additional information such as metadata and autodocumentation information). + +**You should comment you source code.** General tips on commenting: + +- ALWAYS put a **global file comment** at the top of a file to make it [self-contained](self_contained.md). It should include: + - **Description of what the file actually does.** This is extremely important for [readability](readability.md), documentation and quick orientation. If a new programmer comes looking for a specific part of the code, he may waste hours on searching the wrong files just because the idiotic author couldn't be bothered to include fucking three sentences at the start of the file. [Modern](modern.md) program just don't fucking do this anymore, this is just [shit](shit.md). + - [License](license.md)/[waiver](waiver.md), either full text or link. Even if your repo contains a global license (which it should), it's good for the file to carry the license because the file may just be copy pasted on its own into some other project and then it will appear as having no license. + - **Name/nick of the author(s)** and roughly the date of creation (year is enough). This firstly helps legally assess [copyright](copyright.md) (who and for how long holds the copyright) and secondly helps others contact the author in case of encountering something weird in the code. +- Comment specific blocks of code with **keywords** -- this will help searching the code with tools like [grep](grep.md). E.g. in game's code add comment `// player: shoot, fire` to the part of code that handles player's shooting so that someone searching for any one of these two words will be directed here. +- All functions (maybe with exceptions of trivial one-liners) should come with a comment documenting: + - **Behavior** of the function, what it does and also how it does that (Is the function slow? Is it safe? Does it perform checks of arguments? Does it have [side effects](side_effect.md)? ...). + - **Meaning of all arguments** and if needed their possible values. + - **Return value meaning**. +- You may decide to use comment format of some [autodoc](autodoc.md) system such as [doxygen](doxygen.md) -- it costs nothing and helps firstly unify the style of your comments and secondly, obviously, generate automatic documentation of your code, as well as possibly automatically process it in other ways. +- TODO: moar \ No newline at end of file diff --git a/lrs.md b/lrs.md index 8f9ca9a..f6dead9 100644 --- a/lrs.md +++ b/lrs.md @@ -16,7 +16,7 @@ The definition here is not strict but rather fuzzy, it is in a form of ideas, st - Being [free culture](free_culture.md), i.e. LRS programs are free as a whole, including art assets, data etc. - Minimizing [dependencies](dependency.md), even those such as standard library or relying on OS concepts such as files or threads, even indirect ones such as build systems and even non-software ones (e.g. avoiding [floating point](float.md), GPU, 64bit etc.). - Very portable, non-discriminating, i.e. being written in a portable language (C etc.), using as little resources as possible (RAM, CPU, ...) and so on. -- Future-proof, not controlled by anyone (should follow from other points). +- [Future-proof](future_proof.md), [self-contained](self_contained.md), not controlled by anyone (should follow from other points). - [Hacking](hacking.md) friendly and inviting to improvements and customization. - Built on top of other LRS technology such as the [C99](c.md) language, Unix OS, our own libraries etc. - Simple permissive licensing (being suckless legally) with great preference of [public domain](public_domain.md), e.g. with [CC0](cc0.md). diff --git a/modern.md b/modern.md new file mode 100644 index 0000000..5179dbb --- /dev/null +++ b/modern.md @@ -0,0 +1,3 @@ +# Modern + +Modern [software](software.md) might as well be synonymous with [shitty](shit.md) software. \ No newline at end of file