From ab4de018e2169fb645292c12cddbdc36df9e3d78 Mon Sep 17 00:00:00 2001 From: jamessspanggg Date: Sun, 5 Apr 2020 16:24:07 +0800 Subject: [PATCH 1/3] Merge basic/intermediate/advanced in code quality --- .../basic/avoidEmptyCatchBlocks/index.md | 5 -- .../basic/avoidEmptyCatchBlocks/text.md | 14 ---- .../basic/deleteDeadCode/index.md | 5 -- .../basic/deleteDeadCode/text.md | 14 ---- .../basic/dontRecycleVarsOrParams/index.md | 5 -- .../basic/dontRecycleVarsOrParams/text.md | 62 ------------------ codeQuality/avoidShortcuts/basic/index.md | 5 -- codeQuality/avoidShortcuts/basic/path.md | 1 - .../basic/q-essay-badPractice.md | 48 -------------- codeQuality/avoidShortcuts/basic/text.md | 10 --- .../basic/useDefaultBranch/index.md | 5 -- .../basic/useDefaultBranch/text.md | 33 ---------- codeQuality/avoidShortcuts/index.md | 5 -- .../avoidShortcuts/intermediate/index.md | 5 -- .../minimiseCodeDuplication/index.md | 5 -- .../minimiseCodeDuplication/text.md | 20 ------ .../minimiseVariableScope/index.md | 5 -- .../minimiseVariableScope/text.md | 22 ------- .../avoidShortcuts/intermediate/path.md | 1 - .../avoidShortcuts/intermediate/text.md | 8 --- .../avoidShortcuts/introduction/index.md | 5 -- .../avoidShortcuts/introduction/text.md | 14 ---- codeQuality/avoidShortcuts/path.md | 1 - codeQuality/avoidShortcuts/text.md | 9 --- codeQuality/commentMinimally/basic/index.md | 5 -- codeQuality/commentMinimally/basic/path.md | 1 - codeQuality/commentMinimally/basic/text.md | 8 --- .../{basic => }/dontRepeatObvious/index.md | 0 .../{basic => }/dontRepeatObvious/text.md | 0 .../exercises.md | 0 .../explainWhatWhyNotHow/index.md | 0 .../q-tick-comments.md | 0 .../explainWhatWhyNotHow/text.md | 3 + .../commentMinimally/intermediate/index.md | 5 -- .../commentMinimally/intermediate/path.md | 1 - .../commentMinimally/intermediate/text.md | 7 -- codeQuality/commentMinimally/text.md | 5 +- .../{basic => }/writeToReader/example-java.md | 0 .../writeToReader/example-python.md | 0 .../{basic => }/writeToReader/index.md | 0 .../{basic => }/writeToReader/text.md | 0 codeQuality/index.md | 2 +- .../maximiseReadability/advanced/index.md | 5 -- .../maximiseReadability/advanced/path.md | 1 - .../maximiseReadability/advanced/text.md | 7 -- .../example-java.md | 0 .../example-python.md | 0 .../avoidComplicatedExpressions/index.md | 0 .../avoidComplicatedExpressions/text.md | 0 .../images/arrowheadStyle.png | Bin .../{basic => }/avoidDeepNesting/index.md | 0 .../{basic => }/avoidDeepNesting/text.md | 6 +- .../{basic => }/avoidLongMethods/index.md | 0 .../{basic => }/avoidLongMethods/text.md | 0 .../avoidMagicNumbers/example-java.md | 0 .../avoidMagicNumbers/example-python.md | 0 .../{basic => }/avoidMagicNumbers/index.md | 0 .../{basic => }/avoidMagicNumbers/text.md | 0 .../exercises.md | 1 - .../avoidPrematureOptimizations/index.md | 0 .../q-tick-drawback.md | 2 +- .../q-tick-saying.md | 0 .../avoidPrematureOptimizations/text.md | 3 + .../maximiseReadability/basic/index.md | 5 -- codeQuality/maximiseReadability/basic/path.md | 1 - codeQuality/maximiseReadability/basic/text.md | 11 ---- .../dontTripReader/index.md | 0 .../{intermediate => }/dontTripReader/text.md | 0 .../maximiseReadability/intermediate/index.md | 5 -- .../maximiseReadability/intermediate/path.md | 1 - .../maximiseReadability/intermediate/text.md | 11 ---- .../{basic => }/makeCodeObvious/index.md | 0 .../{basic => }/makeCodeObvious/text.md | 0 .../makeHappyPathProminent/index.md | 0 .../makeHappyPathProminent/text.md | 0 .../practiceKISSing/index.md | 0 .../practiceKISSing/text.md | 0 .../slapHard}/exercises.md | 2 +- .../{intermediate => }/slapHard/index.md | 0 .../q-tick-trueFalse.md | 0 .../{intermediate => }/slapHard/text.md | 5 +- .../structureCodeLogically/index.md | 0 .../structureCodeLogically/text.md | 0 codeQuality/maximiseReadability/text.md | 14 +++- .../avoidMisleadingNames/index.md | 0 .../avoidMisleadingNames/text.md | 0 codeQuality/nameWell/basic/index.md | 5 -- codeQuality/nameWell/basic/path.md | 1 - codeQuality/nameWell/basic/text.md | 8 --- codeQuality/nameWell/intermediate/index.md | 5 -- codeQuality/nameWell/intermediate/path.md | 1 - codeQuality/nameWell/intermediate/text.md | 9 --- .../notTooLongNorShort/index.md | 0 .../notTooLongNorShort/text.md | 0 .../{basic => }/nounsAndVerbsAsNames/index.md | 0 .../{basic => }/nounsAndVerbsAsNames/text.md | 0 codeQuality/nameWell/text.md | 7 +- .../useNameExplain/index.md | 0 .../{intermediate => }/useNameExplain/text.md | 0 .../{basic => }/useStandardWords/index.md | 0 .../{basic => }/useStandardWords/text.md | 0 codeQuality/print.md | 35 +++++++--- common/outcomes.md | 34 +++++++--- 103 files changed, 85 insertions(+), 444 deletions(-) delete mode 100644 codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/index.md delete mode 100644 codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/text.md delete mode 100644 codeQuality/avoidShortcuts/basic/deleteDeadCode/index.md delete mode 100644 codeQuality/avoidShortcuts/basic/deleteDeadCode/text.md delete mode 100644 codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/index.md delete mode 100644 codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/text.md delete mode 100644 codeQuality/avoidShortcuts/basic/index.md delete mode 100644 codeQuality/avoidShortcuts/basic/path.md delete mode 100644 codeQuality/avoidShortcuts/basic/q-essay-badPractice.md delete mode 100644 codeQuality/avoidShortcuts/basic/text.md delete mode 100644 codeQuality/avoidShortcuts/basic/useDefaultBranch/index.md delete mode 100644 codeQuality/avoidShortcuts/basic/useDefaultBranch/text.md delete mode 100644 codeQuality/avoidShortcuts/index.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/index.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/index.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/text.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/index.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/text.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/path.md delete mode 100644 codeQuality/avoidShortcuts/intermediate/text.md delete mode 100644 codeQuality/avoidShortcuts/introduction/index.md delete mode 100644 codeQuality/avoidShortcuts/introduction/text.md delete mode 100644 codeQuality/avoidShortcuts/path.md delete mode 100644 codeQuality/avoidShortcuts/text.md delete mode 100644 codeQuality/commentMinimally/basic/index.md delete mode 100644 codeQuality/commentMinimally/basic/path.md delete mode 100644 codeQuality/commentMinimally/basic/text.md rename codeQuality/commentMinimally/{basic => }/dontRepeatObvious/index.md (100%) rename codeQuality/commentMinimally/{basic => }/dontRepeatObvious/text.md (100%) rename codeQuality/commentMinimally/{intermediate => explainWhatWhyNotHow}/exercises.md (100%) rename codeQuality/commentMinimally/{intermediate => }/explainWhatWhyNotHow/index.md (100%) rename codeQuality/commentMinimally/{intermediate => explainWhatWhyNotHow}/q-tick-comments.md (100%) rename codeQuality/commentMinimally/{intermediate => }/explainWhatWhyNotHow/text.md (98%) delete mode 100644 codeQuality/commentMinimally/intermediate/index.md delete mode 100644 codeQuality/commentMinimally/intermediate/path.md delete mode 100644 codeQuality/commentMinimally/intermediate/text.md rename codeQuality/commentMinimally/{basic => }/writeToReader/example-java.md (100%) rename codeQuality/commentMinimally/{basic => }/writeToReader/example-python.md (100%) rename codeQuality/commentMinimally/{basic => }/writeToReader/index.md (100%) rename codeQuality/commentMinimally/{basic => }/writeToReader/text.md (100%) delete mode 100644 codeQuality/maximiseReadability/advanced/index.md delete mode 100644 codeQuality/maximiseReadability/advanced/path.md delete mode 100644 codeQuality/maximiseReadability/advanced/text.md rename codeQuality/maximiseReadability/{basic => }/avoidComplicatedExpressions/example-java.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidComplicatedExpressions/example-python.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidComplicatedExpressions/index.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidComplicatedExpressions/text.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidDeepNesting/images/arrowheadStyle.png (100%) rename codeQuality/maximiseReadability/{basic => }/avoidDeepNesting/index.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidDeepNesting/text.md (72%) rename codeQuality/maximiseReadability/{basic => }/avoidLongMethods/index.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidLongMethods/text.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidMagicNumbers/example-java.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidMagicNumbers/example-python.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidMagicNumbers/index.md (100%) rename codeQuality/maximiseReadability/{basic => }/avoidMagicNumbers/text.md (100%) rename codeQuality/maximiseReadability/{intermediate => avoidPrematureOptimizations}/exercises.md (78%) rename codeQuality/maximiseReadability/{intermediate => }/avoidPrematureOptimizations/index.md (100%) rename codeQuality/maximiseReadability/{intermediate => avoidPrematureOptimizations}/q-tick-drawback.md (86%) rename codeQuality/maximiseReadability/{intermediate => avoidPrematureOptimizations}/q-tick-saying.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/avoidPrematureOptimizations/text.md (98%) delete mode 100644 codeQuality/maximiseReadability/basic/index.md delete mode 100644 codeQuality/maximiseReadability/basic/path.md delete mode 100644 codeQuality/maximiseReadability/basic/text.md rename codeQuality/maximiseReadability/{intermediate => }/dontTripReader/index.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/dontTripReader/text.md (100%) delete mode 100644 codeQuality/maximiseReadability/intermediate/index.md delete mode 100644 codeQuality/maximiseReadability/intermediate/path.md delete mode 100644 codeQuality/maximiseReadability/intermediate/text.md rename codeQuality/maximiseReadability/{basic => }/makeCodeObvious/index.md (100%) rename codeQuality/maximiseReadability/{basic => }/makeCodeObvious/text.md (100%) rename codeQuality/maximiseReadability/{advanced => }/makeHappyPathProminent/index.md (100%) rename codeQuality/maximiseReadability/{advanced => }/makeHappyPathProminent/text.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/practiceKISSing/index.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/practiceKISSing/text.md (100%) rename codeQuality/{avoidShortcuts/basic => maximiseReadability/slapHard}/exercises.md (60%) rename codeQuality/maximiseReadability/{intermediate => }/slapHard/index.md (100%) rename codeQuality/maximiseReadability/{intermediate => slapHard}/q-tick-trueFalse.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/slapHard/text.md (86%) rename codeQuality/maximiseReadability/{intermediate => }/structureCodeLogically/index.md (100%) rename codeQuality/maximiseReadability/{intermediate => }/structureCodeLogically/text.md (100%) rename codeQuality/nameWell/{intermediate => }/avoidMisleadingNames/index.md (100%) rename codeQuality/nameWell/{intermediate => }/avoidMisleadingNames/text.md (100%) delete mode 100644 codeQuality/nameWell/basic/index.md delete mode 100644 codeQuality/nameWell/basic/path.md delete mode 100644 codeQuality/nameWell/basic/text.md delete mode 100644 codeQuality/nameWell/intermediate/index.md delete mode 100644 codeQuality/nameWell/intermediate/path.md delete mode 100644 codeQuality/nameWell/intermediate/text.md rename codeQuality/nameWell/{intermediate => }/notTooLongNorShort/index.md (100%) rename codeQuality/nameWell/{intermediate => }/notTooLongNorShort/text.md (100%) rename codeQuality/nameWell/{basic => }/nounsAndVerbsAsNames/index.md (100%) rename codeQuality/nameWell/{basic => }/nounsAndVerbsAsNames/text.md (100%) rename codeQuality/nameWell/{intermediate => }/useNameExplain/index.md (100%) rename codeQuality/nameWell/{intermediate => }/useNameExplain/text.md (100%) rename codeQuality/nameWell/{basic => }/useStandardWords/index.md (100%) rename codeQuality/nameWell/{basic => }/useStandardWords/text.md (100%) diff --git a/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/index.md b/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/index.md deleted file mode 100644 index 8dda311f06..0000000000 --- a/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Avoid Empty Catch Blocks" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/text.md b/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/text.md deleted file mode 100644 index b60d4e5a7e..0000000000 --- a/codeQuality/avoidShortcuts/basic/avoidEmptyCatchBlocks/text.md +++ /dev/null @@ -1,14 +0,0 @@ -Avoid Empty Catch Blocks - - - -{{ icon_outcome }} Can improve code quality using technique: avoid empty catch blocks - -
- -Never write an empty `catch` statement. At least give a comment to explain why the `catch` block is left empty. - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/deleteDeadCode/index.md b/codeQuality/avoidShortcuts/basic/deleteDeadCode/index.md deleted file mode 100644 index dfe1752bd6..0000000000 --- a/codeQuality/avoidShortcuts/basic/deleteDeadCode/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Delete Dead Code" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/deleteDeadCode/text.md b/codeQuality/avoidShortcuts/basic/deleteDeadCode/text.md deleted file mode 100644 index 6e2f48335c..0000000000 --- a/codeQuality/avoidShortcuts/basic/deleteDeadCode/text.md +++ /dev/null @@ -1,14 +0,0 @@ -Delete Dead Code - - - -{{ icon_outcome }} Can improve code quality using technique: delete dead code - -
- -We all feel reluctant to delete code we have painstakingly written, even if we have no use for that code any more ("I spent a lot of time writing that code; what if we need it again?"). Consider all code as baggage you have to carry; get rid of unused code the moment it becomes redundant. If you need that code again, simply recover it from the revision control tool you are using. Deleting code you wrote previously is a sign that you are improving. - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/index.md b/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/index.md deleted file mode 100644 index 846018329b..0000000000 --- a/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Do Not Recycle Variables or Parameters" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/text.md b/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/text.md deleted file mode 100644 index b70fdb3614..0000000000 --- a/codeQuality/avoidShortcuts/basic/dontRecycleVarsOrParams/text.md +++ /dev/null @@ -1,62 +0,0 @@ -Don't Recycle Variables or Parameters - - - -{{ icon_outcome }} Can improve code quality using technique: don't recycle variables or parameters - -
- -* Use one variable for one purpose. Do not reuse a variable for a different purpose other than its intended one, just because the data type is the same. -* Do not reuse formal parameters as local variables inside the method. - - - -{{bad}} - -
- -```java -double computeRectangleArea(double length, double width) { - length = length * width; - return length; -} -``` -
-
- -```python -def compute_rectangle_area(length, width): - length = length * width - return length -``` - -
- -{{good}} - -
- -```java -double computeRectangleArea(double length, double width) { - double area; - area = length * width; - return area; -} -``` -
-
- -```python -def compute_rectangle_area(length, width): - area = length * width - return area -} -``` -
- - - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/index.md b/codeQuality/avoidShortcuts/basic/index.md deleted file mode 100644 index 0a234b19f2..0000000000 --- a/codeQuality/avoidShortcuts/basic/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts: Basic" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/path.md b/codeQuality/avoidShortcuts/basic/path.md deleted file mode 100644 index db152bb345..0000000000 --- a/codeQuality/avoidShortcuts/basic/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Error-Prone Practices → Basic → diff --git a/codeQuality/avoidShortcuts/basic/q-essay-badPractice.md b/codeQuality/avoidShortcuts/basic/q-essay-badPractice.md deleted file mode 100644 index b7f2c4a70a..0000000000 --- a/codeQuality/avoidShortcuts/basic/q-essay-badPractice.md +++ /dev/null @@ -1,48 +0,0 @@ - - - -Which of these are unsafe coding practices? - -- [ ] a. `case` statements without a `default` clause - -- [ ] b. Omitting braces when a code block has only one statement - - e.g writing this - - ``` - if(isProper) - return PROPER_AMOUNT; - ``` - - instead of - - ``` - if(isProper){ - return PROPER_AMOUNT; - } - ``` - -- [ ] c. Using a variable just to explain what’s going on - - e.g.writing this - - ``` - boolean isProper = notNull && notEmpty; - return isProper; - ``` - - instead of - - ``` - return notNull && notEmpty; - ``` - -
- -a, b. - -Reason why [c] is not a bad practice: The extra variable helps to make the code more understandable because it makes the intent of the formula clearer. - -
- - diff --git a/codeQuality/avoidShortcuts/basic/text.md b/codeQuality/avoidShortcuts/basic/text.md deleted file mode 100644 index fec28825c2..0000000000 --- a/codeQuality/avoidShortcuts/basic/text.md +++ /dev/null @@ -1,10 +0,0 @@ -Basic - -
- - - - - - -
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/useDefaultBranch/index.md b/codeQuality/avoidShortcuts/basic/useDefaultBranch/index.md deleted file mode 100644 index 80b5bd3e9f..0000000000 --- a/codeQuality/avoidShortcuts/basic/useDefaultBranch/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Use Default Branch" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/basic/useDefaultBranch/text.md b/codeQuality/avoidShortcuts/basic/useDefaultBranch/text.md deleted file mode 100644 index 70a69385ad..0000000000 --- a/codeQuality/avoidShortcuts/basic/useDefaultBranch/text.md +++ /dev/null @@ -1,33 +0,0 @@ -Use the Default Branch - - - -{{ icon_outcome }} Can improve code quality using technique: use the default branch - -
- -Always include a default branch in `case` statements. - -Furthermore, use it for the intended default action and not just to execute the last option. If there is no default action, you can use the 'default' branch to detect errors (i.e. if execution reached the `default` branch, throw an exception). This also applies to the final `else` of an `if-else` construct. That is, the final `else` should mean 'everything else', and not the final option. Do not use `else` when an `if` condition can be explicitly specified, unless there is absolutely no other possibility. - - - -{{bad}} -```java -if (red) print "red"; -else print "blue"; -``` -{{good}} -```java -if (red) print "red"; -else if (blue) print "blue"; -else error("incorrect input"); -``` - - - - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/index.md b/codeQuality/avoidShortcuts/index.md deleted file mode 100644 index 36ae2409cf..0000000000 --- a/codeQuality/avoidShortcuts/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/index.md b/codeQuality/avoidShortcuts/intermediate/index.md deleted file mode 100644 index 2bb5de6c65..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts: Intermediate" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/index.md b/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/index.md deleted file mode 100644 index 0688999b84..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Minimize Code Duplication" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/text.md b/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/text.md deleted file mode 100644 index 55662b18ea..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/minimiseCodeDuplication/text.md +++ /dev/null @@ -1,20 +0,0 @@ -Minimize Code Duplication - - - -{{ icon_outcome }} Can improve code quality using technique: minimize code duplication - -
- -**Code duplication, especially when you copy-paste-modify code, often indicates a poor quality implementation.** While it may not be possible to have zero duplication, always think twice before duplicating code; most often there is a better alternative. - -This guideline is closely related to the DRY Principle. - - - - - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/index.md b/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/index.md deleted file mode 100644 index c65f6d6312..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Coding Best Practices: [Practice] Minimize Scope of Variables" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/text.md b/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/text.md deleted file mode 100644 index 8d3af1d9b5..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/minimiseVariableScope/text.md +++ /dev/null @@ -1,22 +0,0 @@ -Minimize Scope of Variables - - - -{{ icon_outcome }} Can improve code quality using technique: minimise scope of variables - -
- -**Minimize global variables**. Global variables may be the most convenient way to pass information around, but they do create implicit links between code segments that use the global variable. Avoid them as much as possible. - -**Define variables in the least possible scope**. For example, if the variable is used only within the `if` block of the conditional statement, it should be declared inside that `if` block. - ->**The most powerful technique for minimizing the scope of a local variable is to declare it where it is first used.** -- _Effective Java_, by Joshua Bloch - -{{ icon_resource }} Resources: - -* [Refactoring: Reduce Scope of Variable](https://refactoring.com/catalog/reduceScopeOfVariable.html) - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/intermediate/path.md b/codeQuality/avoidShortcuts/intermediate/path.md deleted file mode 100644 index f221f02556..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Error-Prone Practices → Intermediate → diff --git a/codeQuality/avoidShortcuts/intermediate/text.md b/codeQuality/avoidShortcuts/intermediate/text.md deleted file mode 100644 index f4592a3699..0000000000 --- a/codeQuality/avoidShortcuts/intermediate/text.md +++ /dev/null @@ -1,8 +0,0 @@ -Intermediate - -
- - - - -
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/introduction/index.md b/codeQuality/avoidShortcuts/introduction/index.md deleted file mode 100644 index 7fcad712e4..0000000000 --- a/codeQuality/avoidShortcuts/introduction/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts: Introduction" - - - \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/introduction/text.md b/codeQuality/avoidShortcuts/introduction/text.md deleted file mode 100644 index 48e9df14be..0000000000 --- a/codeQuality/avoidShortcuts/introduction/text.md +++ /dev/null @@ -1,14 +0,0 @@ -Introduction - - - -{{ icon_outcome }} Can explain the need for avoiding error-prone shortcuts - -
- -It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them. - -
- -
-
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/path.md b/codeQuality/avoidShortcuts/path.md deleted file mode 100644 index 3bfd1ce095..0000000000 --- a/codeQuality/avoidShortcuts/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Error-Prone Practices → diff --git a/codeQuality/avoidShortcuts/text.md b/codeQuality/avoidShortcuts/text.md deleted file mode 100644 index 9b37011d2a..0000000000 --- a/codeQuality/avoidShortcuts/text.md +++ /dev/null @@ -1,9 +0,0 @@ -Guideline: Avoid Unsafe Shortcuts - -
- - - - - -
\ No newline at end of file diff --git a/codeQuality/commentMinimally/basic/index.md b/codeQuality/commentMinimally/basic/index.md deleted file mode 100644 index 7e01860c7f..0000000000 --- a/codeQuality/commentMinimally/basic/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Comment Minimally, but Sufficiently: Basic" - - - \ No newline at end of file diff --git a/codeQuality/commentMinimally/basic/path.md b/codeQuality/commentMinimally/basic/path.md deleted file mode 100644 index 066f8fb352..0000000000 --- a/codeQuality/commentMinimally/basic/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Comments → Basic → diff --git a/codeQuality/commentMinimally/basic/text.md b/codeQuality/commentMinimally/basic/text.md deleted file mode 100644 index 0fc0617755..0000000000 --- a/codeQuality/commentMinimally/basic/text.md +++ /dev/null @@ -1,8 +0,0 @@ -Basic - -
- - - - -
\ No newline at end of file diff --git a/codeQuality/commentMinimally/basic/dontRepeatObvious/index.md b/codeQuality/commentMinimally/dontRepeatObvious/index.md similarity index 100% rename from codeQuality/commentMinimally/basic/dontRepeatObvious/index.md rename to codeQuality/commentMinimally/dontRepeatObvious/index.md diff --git a/codeQuality/commentMinimally/basic/dontRepeatObvious/text.md b/codeQuality/commentMinimally/dontRepeatObvious/text.md similarity index 100% rename from codeQuality/commentMinimally/basic/dontRepeatObvious/text.md rename to codeQuality/commentMinimally/dontRepeatObvious/text.md diff --git a/codeQuality/commentMinimally/intermediate/exercises.md b/codeQuality/commentMinimally/explainWhatWhyNotHow/exercises.md similarity index 100% rename from codeQuality/commentMinimally/intermediate/exercises.md rename to codeQuality/commentMinimally/explainWhatWhyNotHow/exercises.md diff --git a/codeQuality/commentMinimally/intermediate/explainWhatWhyNotHow/index.md b/codeQuality/commentMinimally/explainWhatWhyNotHow/index.md similarity index 100% rename from codeQuality/commentMinimally/intermediate/explainWhatWhyNotHow/index.md rename to codeQuality/commentMinimally/explainWhatWhyNotHow/index.md diff --git a/codeQuality/commentMinimally/intermediate/q-tick-comments.md b/codeQuality/commentMinimally/explainWhatWhyNotHow/q-tick-comments.md similarity index 100% rename from codeQuality/commentMinimally/intermediate/q-tick-comments.md rename to codeQuality/commentMinimally/explainWhatWhyNotHow/q-tick-comments.md diff --git a/codeQuality/commentMinimally/intermediate/explainWhatWhyNotHow/text.md b/codeQuality/commentMinimally/explainWhatWhyNotHow/text.md similarity index 98% rename from codeQuality/commentMinimally/intermediate/explainWhatWhyNotHow/text.md rename to codeQuality/commentMinimally/explainWhatWhyNotHow/text.md index a472dc0934..c3d6c58187 100644 --- a/codeQuality/commentMinimally/intermediate/explainWhatWhyNotHow/text.md +++ b/codeQuality/commentMinimally/explainWhatWhyNotHow/text.md @@ -61,4 +61,7 @@ return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;
+ + +
\ No newline at end of file diff --git a/codeQuality/commentMinimally/intermediate/index.md b/codeQuality/commentMinimally/intermediate/index.md deleted file mode 100644 index 211901901b..0000000000 --- a/codeQuality/commentMinimally/intermediate/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Comment Minimally, but Sufficiently: Intermediate" - - - \ No newline at end of file diff --git a/codeQuality/commentMinimally/intermediate/path.md b/codeQuality/commentMinimally/intermediate/path.md deleted file mode 100644 index 0a4e6e5fce..0000000000 --- a/codeQuality/commentMinimally/intermediate/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Comments → Intermediate → diff --git a/codeQuality/commentMinimally/intermediate/text.md b/codeQuality/commentMinimally/intermediate/text.md deleted file mode 100644 index a808ec5279..0000000000 --- a/codeQuality/commentMinimally/intermediate/text.md +++ /dev/null @@ -1,7 +0,0 @@ -Intermediate - -
- - - -
\ No newline at end of file diff --git a/codeQuality/commentMinimally/text.md b/codeQuality/commentMinimally/text.md index f5d311e3c6..5af949bb69 100644 --- a/codeQuality/commentMinimally/text.md +++ b/codeQuality/commentMinimally/text.md @@ -3,7 +3,8 @@
- - + + +
\ No newline at end of file diff --git a/codeQuality/commentMinimally/basic/writeToReader/example-java.md b/codeQuality/commentMinimally/writeToReader/example-java.md similarity index 100% rename from codeQuality/commentMinimally/basic/writeToReader/example-java.md rename to codeQuality/commentMinimally/writeToReader/example-java.md diff --git a/codeQuality/commentMinimally/basic/writeToReader/example-python.md b/codeQuality/commentMinimally/writeToReader/example-python.md similarity index 100% rename from codeQuality/commentMinimally/basic/writeToReader/example-python.md rename to codeQuality/commentMinimally/writeToReader/example-python.md diff --git a/codeQuality/commentMinimally/basic/writeToReader/index.md b/codeQuality/commentMinimally/writeToReader/index.md similarity index 100% rename from codeQuality/commentMinimally/basic/writeToReader/index.md rename to codeQuality/commentMinimally/writeToReader/index.md diff --git a/codeQuality/commentMinimally/basic/writeToReader/text.md b/codeQuality/commentMinimally/writeToReader/text.md similarity index 100% rename from codeQuality/commentMinimally/basic/writeToReader/text.md rename to codeQuality/commentMinimally/writeToReader/text.md diff --git a/codeQuality/index.md b/codeQuality/index.md index 3eb3765390..7841c7c77c 100644 --- a/codeQuality/index.md +++ b/codeQuality/index.md @@ -1,7 +1,7 @@ title: "Code Quality" siteNav: mainNav.md -pageNav: 3 +pageNav: 4 diff --git a/codeQuality/maximiseReadability/advanced/index.md b/codeQuality/maximiseReadability/advanced/index.md deleted file mode 100644 index 1a57e09f14..0000000000 --- a/codeQuality/maximiseReadability/advanced/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Maximise Readability: Advanced" - - - \ No newline at end of file diff --git a/codeQuality/maximiseReadability/advanced/path.md b/codeQuality/maximiseReadability/advanced/path.md deleted file mode 100644 index cb998e842d..0000000000 --- a/codeQuality/maximiseReadability/advanced/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Readability → Advanced → diff --git a/codeQuality/maximiseReadability/advanced/text.md b/codeQuality/maximiseReadability/advanced/text.md deleted file mode 100644 index b57d58ee28..0000000000 --- a/codeQuality/maximiseReadability/advanced/text.md +++ /dev/null @@ -1,7 +0,0 @@ -Advanced - -
- - - -
\ No newline at end of file diff --git a/codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/example-java.md b/codeQuality/maximiseReadability/avoidComplicatedExpressions/example-java.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/example-java.md rename to codeQuality/maximiseReadability/avoidComplicatedExpressions/example-java.md diff --git a/codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/example-python.md b/codeQuality/maximiseReadability/avoidComplicatedExpressions/example-python.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/example-python.md rename to codeQuality/maximiseReadability/avoidComplicatedExpressions/example-python.md diff --git a/codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/index.md b/codeQuality/maximiseReadability/avoidComplicatedExpressions/index.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/index.md rename to codeQuality/maximiseReadability/avoidComplicatedExpressions/index.md diff --git a/codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/text.md b/codeQuality/maximiseReadability/avoidComplicatedExpressions/text.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidComplicatedExpressions/text.md rename to codeQuality/maximiseReadability/avoidComplicatedExpressions/text.md diff --git a/codeQuality/maximiseReadability/basic/avoidDeepNesting/images/arrowheadStyle.png b/codeQuality/maximiseReadability/avoidDeepNesting/images/arrowheadStyle.png similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidDeepNesting/images/arrowheadStyle.png rename to codeQuality/maximiseReadability/avoidDeepNesting/images/arrowheadStyle.png diff --git a/codeQuality/maximiseReadability/basic/avoidDeepNesting/index.md b/codeQuality/maximiseReadability/avoidDeepNesting/index.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidDeepNesting/index.md rename to codeQuality/maximiseReadability/avoidDeepNesting/index.md diff --git a/codeQuality/maximiseReadability/basic/avoidDeepNesting/text.md b/codeQuality/maximiseReadability/avoidDeepNesting/text.md similarity index 72% rename from codeQuality/maximiseReadability/basic/avoidDeepNesting/text.md rename to codeQuality/maximiseReadability/avoidDeepNesting/text.md index 750298c634..e532fc4514 100644 --- a/codeQuality/maximiseReadability/basic/avoidDeepNesting/text.md +++ b/codeQuality/maximiseReadability/avoidDeepNesting/text.md @@ -10,7 +10,7 @@ In particular, avoid [_arrowhead_ style code](https://blog.codinghorror.com/flattening-arrow-code/). - +

@@ -18,10 +18,10 @@ In particular, avoid [_arrowhead_ style code](https://blog.codinghorror.com/flat {{ icon_example }} A real code example:

- +
- +
diff --git a/codeQuality/maximiseReadability/basic/avoidLongMethods/index.md b/codeQuality/maximiseReadability/avoidLongMethods/index.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidLongMethods/index.md rename to codeQuality/maximiseReadability/avoidLongMethods/index.md diff --git a/codeQuality/maximiseReadability/basic/avoidLongMethods/text.md b/codeQuality/maximiseReadability/avoidLongMethods/text.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidLongMethods/text.md rename to codeQuality/maximiseReadability/avoidLongMethods/text.md diff --git a/codeQuality/maximiseReadability/basic/avoidMagicNumbers/example-java.md b/codeQuality/maximiseReadability/avoidMagicNumbers/example-java.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidMagicNumbers/example-java.md rename to codeQuality/maximiseReadability/avoidMagicNumbers/example-java.md diff --git a/codeQuality/maximiseReadability/basic/avoidMagicNumbers/example-python.md b/codeQuality/maximiseReadability/avoidMagicNumbers/example-python.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidMagicNumbers/example-python.md rename to codeQuality/maximiseReadability/avoidMagicNumbers/example-python.md diff --git a/codeQuality/maximiseReadability/basic/avoidMagicNumbers/index.md b/codeQuality/maximiseReadability/avoidMagicNumbers/index.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidMagicNumbers/index.md rename to codeQuality/maximiseReadability/avoidMagicNumbers/index.md diff --git a/codeQuality/maximiseReadability/basic/avoidMagicNumbers/text.md b/codeQuality/maximiseReadability/avoidMagicNumbers/text.md similarity index 100% rename from codeQuality/maximiseReadability/basic/avoidMagicNumbers/text.md rename to codeQuality/maximiseReadability/avoidMagicNumbers/text.md diff --git a/codeQuality/maximiseReadability/intermediate/exercises.md b/codeQuality/maximiseReadability/avoidPrematureOptimizations/exercises.md similarity index 78% rename from codeQuality/maximiseReadability/intermediate/exercises.md rename to codeQuality/maximiseReadability/avoidPrematureOptimizations/exercises.md index c1aada1eb7..46f21f020a 100644 --- a/codeQuality/maximiseReadability/intermediate/exercises.md +++ b/codeQuality/maximiseReadability/avoidPrematureOptimizations/exercises.md @@ -1,5 +1,4 @@ - diff --git a/codeQuality/maximiseReadability/intermediate/avoidPrematureOptimizations/index.md b/codeQuality/maximiseReadability/avoidPrematureOptimizations/index.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/avoidPrematureOptimizations/index.md rename to codeQuality/maximiseReadability/avoidPrematureOptimizations/index.md diff --git a/codeQuality/maximiseReadability/intermediate/q-tick-drawback.md b/codeQuality/maximiseReadability/avoidPrematureOptimizations/q-tick-drawback.md similarity index 86% rename from codeQuality/maximiseReadability/intermediate/q-tick-drawback.md rename to codeQuality/maximiseReadability/avoidPrematureOptimizations/q-tick-drawback.md index faae6339c1..63d57eecfc 100644 --- a/codeQuality/maximiseReadability/intermediate/q-tick-drawback.md +++ b/codeQuality/maximiseReadability/avoidPrematureOptimizations/q-tick-drawback.md @@ -1,4 +1,4 @@ - + What are the drawbacks of trying to optimize code too soon? diff --git a/codeQuality/maximiseReadability/intermediate/q-tick-saying.md b/codeQuality/maximiseReadability/avoidPrematureOptimizations/q-tick-saying.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/q-tick-saying.md rename to codeQuality/maximiseReadability/avoidPrematureOptimizations/q-tick-saying.md diff --git a/codeQuality/maximiseReadability/intermediate/avoidPrematureOptimizations/text.md b/codeQuality/maximiseReadability/avoidPrematureOptimizations/text.md similarity index 98% rename from codeQuality/maximiseReadability/intermediate/avoidPrematureOptimizations/text.md rename to codeQuality/maximiseReadability/avoidPrematureOptimizations/text.md index dde768bfeb..3e9f89344c 100644 --- a/codeQuality/maximiseReadability/intermediate/avoidPrematureOptimizations/text.md +++ b/codeQuality/maximiseReadability/avoidPrematureOptimizations/text.md @@ -20,4 +20,7 @@ Note that **there are cases where optimizing takes priority over other things**
+ + +
\ No newline at end of file diff --git a/codeQuality/maximiseReadability/basic/index.md b/codeQuality/maximiseReadability/basic/index.md deleted file mode 100644 index 4a891d4d2b..0000000000 --- a/codeQuality/maximiseReadability/basic/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Maximise Readability: Basic" - - - \ No newline at end of file diff --git a/codeQuality/maximiseReadability/basic/path.md b/codeQuality/maximiseReadability/basic/path.md deleted file mode 100644 index ca39f78e15..0000000000 --- a/codeQuality/maximiseReadability/basic/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Readability → Basic → diff --git a/codeQuality/maximiseReadability/basic/text.md b/codeQuality/maximiseReadability/basic/text.md deleted file mode 100644 index 426a1765ad..0000000000 --- a/codeQuality/maximiseReadability/basic/text.md +++ /dev/null @@ -1,11 +0,0 @@ -Basic - -
- - - - - - - -
\ No newline at end of file diff --git a/codeQuality/maximiseReadability/intermediate/dontTripReader/index.md b/codeQuality/maximiseReadability/dontTripReader/index.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/dontTripReader/index.md rename to codeQuality/maximiseReadability/dontTripReader/index.md diff --git a/codeQuality/maximiseReadability/intermediate/dontTripReader/text.md b/codeQuality/maximiseReadability/dontTripReader/text.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/dontTripReader/text.md rename to codeQuality/maximiseReadability/dontTripReader/text.md diff --git a/codeQuality/maximiseReadability/intermediate/index.md b/codeQuality/maximiseReadability/intermediate/index.md deleted file mode 100644 index ec5fd06155..0000000000 --- a/codeQuality/maximiseReadability/intermediate/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Maximise Readability: Intermediate" - - - \ No newline at end of file diff --git a/codeQuality/maximiseReadability/intermediate/path.md b/codeQuality/maximiseReadability/intermediate/path.md deleted file mode 100644 index 78254f4f26..0000000000 --- a/codeQuality/maximiseReadability/intermediate/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Readability → Intermediate → diff --git a/codeQuality/maximiseReadability/intermediate/text.md b/codeQuality/maximiseReadability/intermediate/text.md deleted file mode 100644 index 43c62aaba6..0000000000 --- a/codeQuality/maximiseReadability/intermediate/text.md +++ /dev/null @@ -1,11 +0,0 @@ -Intermediate - -
- - - - - - - -
\ No newline at end of file diff --git a/codeQuality/maximiseReadability/basic/makeCodeObvious/index.md b/codeQuality/maximiseReadability/makeCodeObvious/index.md similarity index 100% rename from codeQuality/maximiseReadability/basic/makeCodeObvious/index.md rename to codeQuality/maximiseReadability/makeCodeObvious/index.md diff --git a/codeQuality/maximiseReadability/basic/makeCodeObvious/text.md b/codeQuality/maximiseReadability/makeCodeObvious/text.md similarity index 100% rename from codeQuality/maximiseReadability/basic/makeCodeObvious/text.md rename to codeQuality/maximiseReadability/makeCodeObvious/text.md diff --git a/codeQuality/maximiseReadability/advanced/makeHappyPathProminent/index.md b/codeQuality/maximiseReadability/makeHappyPathProminent/index.md similarity index 100% rename from codeQuality/maximiseReadability/advanced/makeHappyPathProminent/index.md rename to codeQuality/maximiseReadability/makeHappyPathProminent/index.md diff --git a/codeQuality/maximiseReadability/advanced/makeHappyPathProminent/text.md b/codeQuality/maximiseReadability/makeHappyPathProminent/text.md similarity index 100% rename from codeQuality/maximiseReadability/advanced/makeHappyPathProminent/text.md rename to codeQuality/maximiseReadability/makeHappyPathProminent/text.md diff --git a/codeQuality/maximiseReadability/intermediate/practiceKISSing/index.md b/codeQuality/maximiseReadability/practiceKISSing/index.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/practiceKISSing/index.md rename to codeQuality/maximiseReadability/practiceKISSing/index.md diff --git a/codeQuality/maximiseReadability/intermediate/practiceKISSing/text.md b/codeQuality/maximiseReadability/practiceKISSing/text.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/practiceKISSing/text.md rename to codeQuality/maximiseReadability/practiceKISSing/text.md diff --git a/codeQuality/avoidShortcuts/basic/exercises.md b/codeQuality/maximiseReadability/slapHard/exercises.md similarity index 60% rename from codeQuality/avoidShortcuts/basic/exercises.md rename to codeQuality/maximiseReadability/slapHard/exercises.md index ab1313e131..0c8244bc4d 100644 --- a/codeQuality/avoidShortcuts/basic/exercises.md +++ b/codeQuality/maximiseReadability/slapHard/exercises.md @@ -1,3 +1,3 @@ - + diff --git a/codeQuality/maximiseReadability/intermediate/slapHard/index.md b/codeQuality/maximiseReadability/slapHard/index.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/slapHard/index.md rename to codeQuality/maximiseReadability/slapHard/index.md diff --git a/codeQuality/maximiseReadability/intermediate/q-tick-trueFalse.md b/codeQuality/maximiseReadability/slapHard/q-tick-trueFalse.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/q-tick-trueFalse.md rename to codeQuality/maximiseReadability/slapHard/q-tick-trueFalse.md diff --git a/codeQuality/maximiseReadability/intermediate/slapHard/text.md b/codeQuality/maximiseReadability/slapHard/text.md similarity index 86% rename from codeQuality/maximiseReadability/intermediate/slapHard/text.md rename to codeQuality/maximiseReadability/slapHard/text.md index 8fc38d33d6..ef5b275eaa 100644 --- a/codeQuality/maximiseReadability/intermediate/slapHard/text.md +++ b/codeQuality/maximiseReadability/slapHard/text.md @@ -31,11 +31,14 @@ displayResult(); - +
+ + +
\ No newline at end of file diff --git a/codeQuality/maximiseReadability/intermediate/structureCodeLogically/index.md b/codeQuality/maximiseReadability/structureCodeLogically/index.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/structureCodeLogically/index.md rename to codeQuality/maximiseReadability/structureCodeLogically/index.md diff --git a/codeQuality/maximiseReadability/intermediate/structureCodeLogically/text.md b/codeQuality/maximiseReadability/structureCodeLogically/text.md similarity index 100% rename from codeQuality/maximiseReadability/intermediate/structureCodeLogically/text.md rename to codeQuality/maximiseReadability/structureCodeLogically/text.md diff --git a/codeQuality/maximiseReadability/text.md b/codeQuality/maximiseReadability/text.md index f1c4802a44..8f6093c394 100644 --- a/codeQuality/maximiseReadability/text.md +++ b/codeQuality/maximiseReadability/text.md @@ -3,8 +3,16 @@
- - - + + + + + + + + + + +
\ No newline at end of file diff --git a/codeQuality/nameWell/intermediate/avoidMisleadingNames/index.md b/codeQuality/nameWell/avoidMisleadingNames/index.md similarity index 100% rename from codeQuality/nameWell/intermediate/avoidMisleadingNames/index.md rename to codeQuality/nameWell/avoidMisleadingNames/index.md diff --git a/codeQuality/nameWell/intermediate/avoidMisleadingNames/text.md b/codeQuality/nameWell/avoidMisleadingNames/text.md similarity index 100% rename from codeQuality/nameWell/intermediate/avoidMisleadingNames/text.md rename to codeQuality/nameWell/avoidMisleadingNames/text.md diff --git a/codeQuality/nameWell/basic/index.md b/codeQuality/nameWell/basic/index.md deleted file mode 100644 index 0b05d75b91..0000000000 --- a/codeQuality/nameWell/basic/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Name Well: Basic" - - - \ No newline at end of file diff --git a/codeQuality/nameWell/basic/path.md b/codeQuality/nameWell/basic/path.md deleted file mode 100644 index 09e0bd0bf7..0000000000 --- a/codeQuality/nameWell/basic/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Naming → Basic → diff --git a/codeQuality/nameWell/basic/text.md b/codeQuality/nameWell/basic/text.md deleted file mode 100644 index 362f24ff7e..0000000000 --- a/codeQuality/nameWell/basic/text.md +++ /dev/null @@ -1,8 +0,0 @@ -Basic - -
- - - - -
\ No newline at end of file diff --git a/codeQuality/nameWell/intermediate/index.md b/codeQuality/nameWell/intermediate/index.md deleted file mode 100644 index c777268b65..0000000000 --- a/codeQuality/nameWell/intermediate/index.md +++ /dev/null @@ -1,5 +0,0 @@ - -title: "Code Quality: [Guideline] Name Well: Intermediate" - - - \ No newline at end of file diff --git a/codeQuality/nameWell/intermediate/path.md b/codeQuality/nameWell/intermediate/path.md deleted file mode 100644 index 270fa6c987..0000000000 --- a/codeQuality/nameWell/intermediate/path.md +++ /dev/null @@ -1 +0,0 @@ -Implementation → Code Quality → Naming → Intermediate → diff --git a/codeQuality/nameWell/intermediate/text.md b/codeQuality/nameWell/intermediate/text.md deleted file mode 100644 index a529212450..0000000000 --- a/codeQuality/nameWell/intermediate/text.md +++ /dev/null @@ -1,9 +0,0 @@ -Intermediate - -
- - - - - -
\ No newline at end of file diff --git a/codeQuality/nameWell/intermediate/notTooLongNorShort/index.md b/codeQuality/nameWell/notTooLongNorShort/index.md similarity index 100% rename from codeQuality/nameWell/intermediate/notTooLongNorShort/index.md rename to codeQuality/nameWell/notTooLongNorShort/index.md diff --git a/codeQuality/nameWell/intermediate/notTooLongNorShort/text.md b/codeQuality/nameWell/notTooLongNorShort/text.md similarity index 100% rename from codeQuality/nameWell/intermediate/notTooLongNorShort/text.md rename to codeQuality/nameWell/notTooLongNorShort/text.md diff --git a/codeQuality/nameWell/basic/nounsAndVerbsAsNames/index.md b/codeQuality/nameWell/nounsAndVerbsAsNames/index.md similarity index 100% rename from codeQuality/nameWell/basic/nounsAndVerbsAsNames/index.md rename to codeQuality/nameWell/nounsAndVerbsAsNames/index.md diff --git a/codeQuality/nameWell/basic/nounsAndVerbsAsNames/text.md b/codeQuality/nameWell/nounsAndVerbsAsNames/text.md similarity index 100% rename from codeQuality/nameWell/basic/nounsAndVerbsAsNames/text.md rename to codeQuality/nameWell/nounsAndVerbsAsNames/text.md diff --git a/codeQuality/nameWell/text.md b/codeQuality/nameWell/text.md index 74bac07c74..390d931aa9 100644 --- a/codeQuality/nameWell/text.md +++ b/codeQuality/nameWell/text.md @@ -3,7 +3,10 @@
- - + + + + +
\ No newline at end of file diff --git a/codeQuality/nameWell/intermediate/useNameExplain/index.md b/codeQuality/nameWell/useNameExplain/index.md similarity index 100% rename from codeQuality/nameWell/intermediate/useNameExplain/index.md rename to codeQuality/nameWell/useNameExplain/index.md diff --git a/codeQuality/nameWell/intermediate/useNameExplain/text.md b/codeQuality/nameWell/useNameExplain/text.md similarity index 100% rename from codeQuality/nameWell/intermediate/useNameExplain/text.md rename to codeQuality/nameWell/useNameExplain/text.md diff --git a/codeQuality/nameWell/basic/useStandardWords/index.md b/codeQuality/nameWell/useStandardWords/index.md similarity index 100% rename from codeQuality/nameWell/basic/useStandardWords/index.md rename to codeQuality/nameWell/useStandardWords/index.md diff --git a/codeQuality/nameWell/basic/useStandardWords/text.md b/codeQuality/nameWell/useStandardWords/text.md similarity index 100% rename from codeQuality/nameWell/basic/useStandardWords/text.md rename to codeQuality/nameWell/useStandardWords/text.md diff --git a/codeQuality/print.md b/codeQuality/print.md index 5680a1e2cd..4b946a3b05 100644 --- a/codeQuality/print.md +++ b/codeQuality/print.md @@ -17,9 +17,17 @@ title: "Code Quality [Printable]" ## Guideline: Maximise Readability - - - + + + + + + + + + + + ## Guideline: Follow a Standard @@ -30,21 +38,28 @@ title: "Code Quality [Printable]" ## Guideline: Name Well - - + + + + + ## Guideline: Avoid Unsafe Shortcuts - - - + + + + + + ## Guideline: Comment Minimally, But Sufficiently - - + + + diff --git a/common/outcomes.md b/common/outcomes.md index b690c5d443..98037f65e4 100644 --- a/common/outcomes.md +++ b/common/outcomes.md @@ -166,21 +166,37 @@ pageNav: 3 - - - + + + + + + + + + + + - - + + + + + - - + + + + + + - - + + + ### Refactoring From a55bb562fbbdec89b95f76eed78d8775f74047db Mon Sep 17 00:00:00 2001 From: jamessspanggg Date: Sun, 5 Apr 2020 16:25:24 +0800 Subject: [PATCH 2/3] Remove LOs in code quality --- common/outcomes.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/common/outcomes.md b/common/outcomes.md index 98037f65e4..2ad6c22cb0 100644 --- a/common/outcomes.md +++ b/common/outcomes.md @@ -166,37 +166,12 @@ pageNav: 3 - - - - - - - - - - - - - - - - - - - - - - - - - ### Refactoring From f1abcfaa902af3dc20379280a868d3f6b51b0d26 Mon Sep 17 00:00:00 2001 From: jamessspanggg Date: Sun, 5 Apr 2020 16:36:24 +0800 Subject: [PATCH 3/3] Add avoidShorcuts that was missed out --- .../avoidEmptyCatchBlocks/index.md | 5 ++ .../avoidEmptyCatchBlocks/text.md | 14 +++++ .../avoidShortcuts/deleteDeadCode/index.md | 5 ++ .../avoidShortcuts/deleteDeadCode/text.md | 14 +++++ .../dontRecycleVarsOrParams/index.md | 5 ++ .../dontRecycleVarsOrParams/text.md | 62 +++++++++++++++++++ codeQuality/avoidShortcuts/exercises.md | 3 + codeQuality/avoidShortcuts/index.md | 5 ++ .../avoidShortcuts/introduction/index.md | 5 ++ .../avoidShortcuts/introduction/text.md | 14 +++++ .../minimiseCodeDuplication/index.md | 5 ++ .../minimiseCodeDuplication/text.md | 20 ++++++ .../minimiseVariableScope/index.md | 5 ++ .../minimiseVariableScope/text.md | 22 +++++++ codeQuality/avoidShortcuts/path.md | 1 + .../avoidShortcuts/q-essay-badPractice.md | 48 ++++++++++++++ codeQuality/avoidShortcuts/text.md | 19 ++++++ .../avoidShortcuts/useDefaultBranch/index.md | 5 ++ .../avoidShortcuts/useDefaultBranch/text.md | 33 ++++++++++ 19 files changed, 290 insertions(+) create mode 100644 codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/index.md create mode 100644 codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/text.md create mode 100644 codeQuality/avoidShortcuts/deleteDeadCode/index.md create mode 100644 codeQuality/avoidShortcuts/deleteDeadCode/text.md create mode 100644 codeQuality/avoidShortcuts/dontRecycleVarsOrParams/index.md create mode 100644 codeQuality/avoidShortcuts/dontRecycleVarsOrParams/text.md create mode 100644 codeQuality/avoidShortcuts/exercises.md create mode 100644 codeQuality/avoidShortcuts/index.md create mode 100644 codeQuality/avoidShortcuts/introduction/index.md create mode 100644 codeQuality/avoidShortcuts/introduction/text.md create mode 100644 codeQuality/avoidShortcuts/minimiseCodeDuplication/index.md create mode 100644 codeQuality/avoidShortcuts/minimiseCodeDuplication/text.md create mode 100644 codeQuality/avoidShortcuts/minimiseVariableScope/index.md create mode 100644 codeQuality/avoidShortcuts/minimiseVariableScope/text.md create mode 100644 codeQuality/avoidShortcuts/path.md create mode 100644 codeQuality/avoidShortcuts/q-essay-badPractice.md create mode 100644 codeQuality/avoidShortcuts/text.md create mode 100644 codeQuality/avoidShortcuts/useDefaultBranch/index.md create mode 100644 codeQuality/avoidShortcuts/useDefaultBranch/text.md diff --git a/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/index.md b/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/index.md new file mode 100644 index 0000000000..8dda311f06 --- /dev/null +++ b/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Avoid Empty Catch Blocks" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/text.md b/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/text.md new file mode 100644 index 0000000000..b60d4e5a7e --- /dev/null +++ b/codeQuality/avoidShortcuts/avoidEmptyCatchBlocks/text.md @@ -0,0 +1,14 @@ +Avoid Empty Catch Blocks + + + +{{ icon_outcome }} Can improve code quality using technique: avoid empty catch blocks + +
+ +Never write an empty `catch` statement. At least give a comment to explain why the `catch` block is left empty. + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/deleteDeadCode/index.md b/codeQuality/avoidShortcuts/deleteDeadCode/index.md new file mode 100644 index 0000000000..dfe1752bd6 --- /dev/null +++ b/codeQuality/avoidShortcuts/deleteDeadCode/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Delete Dead Code" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/deleteDeadCode/text.md b/codeQuality/avoidShortcuts/deleteDeadCode/text.md new file mode 100644 index 0000000000..6e2f48335c --- /dev/null +++ b/codeQuality/avoidShortcuts/deleteDeadCode/text.md @@ -0,0 +1,14 @@ +Delete Dead Code + + + +{{ icon_outcome }} Can improve code quality using technique: delete dead code + +
+ +We all feel reluctant to delete code we have painstakingly written, even if we have no use for that code any more ("I spent a lot of time writing that code; what if we need it again?"). Consider all code as baggage you have to carry; get rid of unused code the moment it becomes redundant. If you need that code again, simply recover it from the revision control tool you are using. Deleting code you wrote previously is a sign that you are improving. + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/index.md b/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/index.md new file mode 100644 index 0000000000..846018329b --- /dev/null +++ b/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Do Not Recycle Variables or Parameters" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/text.md b/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/text.md new file mode 100644 index 0000000000..b70fdb3614 --- /dev/null +++ b/codeQuality/avoidShortcuts/dontRecycleVarsOrParams/text.md @@ -0,0 +1,62 @@ +Don't Recycle Variables or Parameters + + + +{{ icon_outcome }} Can improve code quality using technique: don't recycle variables or parameters + +
+ +* Use one variable for one purpose. Do not reuse a variable for a different purpose other than its intended one, just because the data type is the same. +* Do not reuse formal parameters as local variables inside the method. + + + +{{bad}} + +
+ +```java +double computeRectangleArea(double length, double width) { + length = length * width; + return length; +} +``` +
+
+ +```python +def compute_rectangle_area(length, width): + length = length * width + return length +``` + +
+ +{{good}} + +
+ +```java +double computeRectangleArea(double length, double width) { + double area; + area = length * width; + return area; +} +``` +
+
+ +```python +def compute_rectangle_area(length, width): + area = length * width + return area +} +``` +
+ + + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/exercises.md b/codeQuality/avoidShortcuts/exercises.md new file mode 100644 index 0000000000..ab1313e131 --- /dev/null +++ b/codeQuality/avoidShortcuts/exercises.md @@ -0,0 +1,3 @@ + + + diff --git a/codeQuality/avoidShortcuts/index.md b/codeQuality/avoidShortcuts/index.md new file mode 100644 index 0000000000..36ae2409cf --- /dev/null +++ b/codeQuality/avoidShortcuts/index.md @@ -0,0 +1,5 @@ + +title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/introduction/index.md b/codeQuality/avoidShortcuts/introduction/index.md new file mode 100644 index 0000000000..7fcad712e4 --- /dev/null +++ b/codeQuality/avoidShortcuts/introduction/index.md @@ -0,0 +1,5 @@ + +title: "Code Quality: [Guideline] Avoid Unsafe Shortcuts: Introduction" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/introduction/text.md b/codeQuality/avoidShortcuts/introduction/text.md new file mode 100644 index 0000000000..48e9df14be --- /dev/null +++ b/codeQuality/avoidShortcuts/introduction/text.md @@ -0,0 +1,14 @@ +Introduction + + + +{{ icon_outcome }} Can explain the need for avoiding error-prone shortcuts + +
+ +It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them. + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/minimiseCodeDuplication/index.md b/codeQuality/avoidShortcuts/minimiseCodeDuplication/index.md new file mode 100644 index 0000000000..0688999b84 --- /dev/null +++ b/codeQuality/avoidShortcuts/minimiseCodeDuplication/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Minimize Code Duplication" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/minimiseCodeDuplication/text.md b/codeQuality/avoidShortcuts/minimiseCodeDuplication/text.md new file mode 100644 index 0000000000..f9b7bb2164 --- /dev/null +++ b/codeQuality/avoidShortcuts/minimiseCodeDuplication/text.md @@ -0,0 +1,20 @@ +Minimize Code Duplication + + + +{{ icon_outcome }} Can improve code quality using technique: minimize code duplication + +
+ +**Code duplication, especially when you copy-paste-modify code, often indicates a poor quality implementation.** While it may not be possible to have zero duplication, always think twice before duplicating code; most often there is a better alternative. + +This guideline is closely related to the DRY Principle. + + + + + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/minimiseVariableScope/index.md b/codeQuality/avoidShortcuts/minimiseVariableScope/index.md new file mode 100644 index 0000000000..c65f6d6312 --- /dev/null +++ b/codeQuality/avoidShortcuts/minimiseVariableScope/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Minimize Scope of Variables" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/minimiseVariableScope/text.md b/codeQuality/avoidShortcuts/minimiseVariableScope/text.md new file mode 100644 index 0000000000..8d3af1d9b5 --- /dev/null +++ b/codeQuality/avoidShortcuts/minimiseVariableScope/text.md @@ -0,0 +1,22 @@ +Minimize Scope of Variables + + + +{{ icon_outcome }} Can improve code quality using technique: minimise scope of variables + +
+ +**Minimize global variables**. Global variables may be the most convenient way to pass information around, but they do create implicit links between code segments that use the global variable. Avoid them as much as possible. + +**Define variables in the least possible scope**. For example, if the variable is used only within the `if` block of the conditional statement, it should be declared inside that `if` block. + +>**The most powerful technique for minimizing the scope of a local variable is to declare it where it is first used.** -- _Effective Java_, by Joshua Bloch + +{{ icon_resource }} Resources: + +* [Refactoring: Reduce Scope of Variable](https://refactoring.com/catalog/reduceScopeOfVariable.html) + +
+ +
+
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/path.md b/codeQuality/avoidShortcuts/path.md new file mode 100644 index 0000000000..3bfd1ce095 --- /dev/null +++ b/codeQuality/avoidShortcuts/path.md @@ -0,0 +1 @@ +Implementation → Code Quality → Error-Prone Practices → diff --git a/codeQuality/avoidShortcuts/q-essay-badPractice.md b/codeQuality/avoidShortcuts/q-essay-badPractice.md new file mode 100644 index 0000000000..416a510718 --- /dev/null +++ b/codeQuality/avoidShortcuts/q-essay-badPractice.md @@ -0,0 +1,48 @@ + + + +Which of these are unsafe coding practices? + +- [ ] a. `case` statements without a `default` clause + +- [ ] b. Omitting braces when a code block has only one statement + + e.g writing this + + ``` + if(isProper) + return PROPER_AMOUNT; + ``` + + instead of + + ``` + if(isProper){ + return PROPER_AMOUNT; + } + ``` + +- [ ] c. Using a variable just to explain what’s going on + + e.g.writing this + + ``` + boolean isProper = notNull && notEmpty; + return isProper; + ``` + + instead of + + ``` + return notNull && notEmpty; + ``` + +
+ +a, b. + +Reason why [c] is not a bad practice: The extra variable helps to make the code more understandable because it makes the intent of the formula clearer. + +
+ + diff --git a/codeQuality/avoidShortcuts/text.md b/codeQuality/avoidShortcuts/text.md new file mode 100644 index 0000000000..d5f14e0b32 --- /dev/null +++ b/codeQuality/avoidShortcuts/text.md @@ -0,0 +1,19 @@ +Guideline: Avoid Unsafe Shortcuts + +
+ + + + + + + + + +
+ +
+ + + +
\ No newline at end of file diff --git a/codeQuality/avoidShortcuts/useDefaultBranch/index.md b/codeQuality/avoidShortcuts/useDefaultBranch/index.md new file mode 100644 index 0000000000..80b5bd3e9f --- /dev/null +++ b/codeQuality/avoidShortcuts/useDefaultBranch/index.md @@ -0,0 +1,5 @@ + +title: "Coding Best Practices: [Practice] Use Default Branch" + + + \ No newline at end of file diff --git a/codeQuality/avoidShortcuts/useDefaultBranch/text.md b/codeQuality/avoidShortcuts/useDefaultBranch/text.md new file mode 100644 index 0000000000..70a69385ad --- /dev/null +++ b/codeQuality/avoidShortcuts/useDefaultBranch/text.md @@ -0,0 +1,33 @@ +Use the Default Branch + + + +{{ icon_outcome }} Can improve code quality using technique: use the default branch + +
+ +Always include a default branch in `case` statements. + +Furthermore, use it for the intended default action and not just to execute the last option. If there is no default action, you can use the 'default' branch to detect errors (i.e. if execution reached the `default` branch, throw an exception). This also applies to the final `else` of an `if-else` construct. That is, the final `else` should mean 'everything else', and not the final option. Do not use `else` when an `if` condition can be explicitly specified, unless there is absolutely no other possibility. + + + +{{bad}} +```java +if (red) print "red"; +else print "blue"; +``` +{{good}} +```java +if (red) print "red"; +else if (blue) print "blue"; +else error("incorrect input"); +``` + + + + +
+ +
+
\ No newline at end of file