From 0cc674d3ce3d4e2f47894a0ab0b5529a170e328b Mon Sep 17 00:00:00 2001 From: doom Date: Sat, 30 Dec 2023 09:46:16 -0800 Subject: [PATCH 1/5] documentation --- .github/guides/STANDARDS.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index c9b988bd07ff..7c13fca69da6 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 waranted 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,nit'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 follwing 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 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) From f7713ffe260a014ffea541ab3cacea58c005050d Mon Sep 17 00:00:00 2001 From: doom Date: Sat, 30 Dec 2023 09:59:12 -0800 Subject: [PATCH 2/5] typo --- .github/guides/STANDARDS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index 7c13fca69da6..d4007f923453 100644 --- a/.github/guides/STANDARDS.md +++ b/.github/guides/STANDARDS.md @@ -91,7 +91,7 @@ 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 waranted 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,nit's usually not going to add much to the quality of the code +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. From 400c04e15413b5102123dd0adc8fa268090d8630 Mon Sep 17 00:00:00 2001 From: doom Date: Sat, 30 Dec 2023 10:06:33 -0800 Subject: [PATCH 3/5] fix --- .github/guides/STANDARDS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index d4007f923453..868425d960f3 100644 --- a/.github/guides/STANDARDS.md +++ b/.github/guides/STANDARDS.md @@ -116,7 +116,7 @@ Good comment, using defines and proper naming conventions if(infected_human.stat == DEAD) infection_rate = FAST_INFECTION_RATE -// infection rate should be reduced mobs that are alive +// infection rate should be reduced for mobs that are alive if(infected_human.stat != DEAD) infection_rate = SLOW_INFECTION_RATE ``` From edab44aaf31f3affbe992f48ed60939b7cda3ce8 Mon Sep 17 00:00:00 2001 From: doom Date: Sat, 30 Dec 2023 10:07:52 -0800 Subject: [PATCH 4/5] typo --- .github/guides/STANDARDS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index 868425d960f3..079a001407a9 100644 --- a/.github/guides/STANDARDS.md +++ b/.github/guides/STANDARDS.md @@ -95,7 +95,7 @@ proper standards, such as using defines and good naming conventions, it's usuall 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 follwing example: +Here is a following example: Bad comment ``` From 3a8ce5cf7ffb88ac7410a21fd298d102169a088b Mon Sep 17 00:00:00 2001 From: doom Date: Sat, 30 Dec 2023 10:12:53 -0800 Subject: [PATCH 5/5] typo --- .github/guides/STANDARDS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/guides/STANDARDS.md b/.github/guides/STANDARDS.md index 079a001407a9..9e4f09af5aa9 100644 --- a/.github/guides/STANDARDS.md +++ b/.github/guides/STANDARDS.md @@ -89,7 +89,7 @@ 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 waranted outside of autodoc +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