diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index c9b988bd07ff..9e4f09af5aa9 100644 --- a/.github/guides/STANDARDS.md +++ b/.github/guides/STANDARDS.md @@ -12,6 +12,7 @@ As with the style guide, you are expected to follow these specifications in orde - [User Interfaces](#user-interfaces) - [Dont override type safety checks](#dont-override-type-safety-checks) - [Do not use text/string based type paths](#do-not-use-textstring-based-type-paths) + - [how to properly use comments](#documenting-logic) - [Other Notes](#other-notes) - [Structural](#structural) - [No duplicated code (Don't repeat yourself)](#no-duplicated-code-dont-repeat-yourself) @@ -87,6 +88,42 @@ var/path_type = /obj/item/baseball_bat var/path_type = "/obj/item/baseball_bat" ``` +## Documenting logic +Sometimes you might want to comment on logic in your proc, however, most of the time this isn't warranted outside of autodoc +There really isn't a need to comment on every line of code that's written, if the code is following +proper standards, such as using defines and good naming conventions, it's usually not going to add much to the quality of the code +But generally, if you're going to comment on some code it's best to comment on things that are not totally obvious +And more importantly comment on why something is happening rather than what is happening. + +Here is a following example: + +Bad comment +``` +// check if mob is dead +if(H.stat == DEAD) + infection_rate = 4 + +// check if mob isn't dead +if(H.stat != DEAD) + infection_rate = 1 +``` + +Good comment, using defines and proper naming conventions +``` +#define FAST_INFECTION_RATE 4 +#define SLOW_INFECTION_RATE 1 +// infection rate should be increased for dead mobs +if(infected_human.stat == DEAD) + infection_rate = FAST_INFECTION_RATE + +// infection rate should be reduced for mobs that are alive +if(infected_human.stat != DEAD) + infection_rate = SLOW_INFECTION_RATE +``` + +notice how for both the comment probably wasn't necessary as it's clear what's happening either way +but it's a bit more clear in the second example because of the defines and naming conventions + ### Other Notes * Code should be modular where possible; if you are working on a new addition, then strongly consider putting it in its own file unless it makes sense to put it with similar ones (i.e. a new tool would go in the "tools.dm" file)