drummyfish/less_retarded_wiki
5
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update

Browse source
This commit is contained in:
Miloslav Ciz 2025-01-08 16:36:13 +01:00
parent 36021baff3
commit 9347555db9
15 changed files with 1932 additions and 1915 deletions
Download patch file Download diff file Expand all files Collapse all files

2
comment.md
View file

@ -8,7 +8,7 @@ While yes, you should write nice, [self documenting](self_documentation.md) code
- **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.
- 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. It also just speeds up navigating in code with your editor -- instead of manually searching through functions all the time you know you can just quickly "CTRL+F" a certain keyword to get where you want.
- Be brief, don't write poetry, too much text and pompous style will make it less readable.
- Functions (maybe with some exceptions like 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)? How are errors handled? ...).