Maxi Contieri

Posted on Oct 11, 2022 • Originally published at maximilianocontieri.com

Code Smell 168 - Undocumented Decisions

#webdev #beginners #programming #tutorial

Code Smells (280 Part Series)

1 Code Smell 01 - Anemic Models 2 Code Smell 02 - Constants and Magic Numbers ... 276 more parts... 3 Code Smell 03 - Functions Are Too Long 4 Code Smell 04 - String Abusers 5 Code Smell 05 - Comment Abusers 6 Code Smell 06 - Too Clever Programmer 7 Code Smell 07 - Boolean Variables 8 Code Smell 08 - Long Chains Of Collaborations 9 Code Smell 09 - Dead Code 10 Code Smell 10 - Too Many Arguments 11 Code Smell 11 - Subclassification for Code Reuse 12 Code Smell 12 - Null 13 Code Smell 13 - Empty Constructors 14 Code Smell 14 - God Objects 15 Code Smell 15 - Missed Preconditions 16 Code Smell 16 - Ripple Effect 17 Code Smell 17 - Global Functions 18 Code Smell 18 — Static Functions 19 Code Smell 19 — Optional Arguments 20 Code Smell 20 - Premature Optimization 21 Code Smell 21 - Anonymous Functions Abusers 22 Code Smell 22 - Helpers 23 Code Smell 23 - Instance Type Checking 24 Code Smell 24 - Boolean Coercions 25 Code Smell 25 - Pattern Abusers 26 Code Smell 26 - Exceptions Polluting 27 Code Smell 27 - Associative Arrays 28 Code Smell 28 - Setters 29 Code Smell 29 - Settings/Configs 30 Code Smell 30 - Mocking Business 31 Code Smell 31 - Accidental Methods on Business Objects 32 Code Smell 32 - Singletons 33 Code Smell 33 - Abbreviations 34 Code Smell 34 - Too Many Attributes 35 Code Smell 35 - State as Properties 36 Code Smell 36 - Switch/case/elseif/else/if statements 37 Code Smell 37 - Protected Attributes 38 Code Smell 38 - Abstract Names 39 Code Smell 39 - new Date() 40 Code Smell 40 - DTOs 41 Code Smell 41 - Regular Expression Abusers 42 Code Smell 42 - Warnings/Strict Mode Off 43 Code Smell 43 - Concrete Classes Subclassified 44 Code Smell 44 - Magic Corrections 45 Code Smell 45 - Not Polymorphic 46 Code Smell 46 - Repeated Code 47 Code Smell 47 - Diagrams 48 Code Smell 48 - Code Without Standards 49 Code Smell 49 - Caches 50 Code Smell 50 - Object Keys 51 Code Smell 51 - Double Negatives 52 Code Smell 52 - Fragile Tests 53 Code Smell 53 - Explicit Iteration 54 Code Smell 54 - Anchor Boats 55 Code Smell 55 - Object Orgy 56 Code Smell 56 - Preprocessors 57 Code Smell 57 - Versioned Functions 58 Code Smell 58 - Yo-yo Problem 59 Code Smell 59 - Basic / Do Functions 60 Code Smell 60 - Global Classes 61 Code Smell 61 - Coupling to Classes 62 Code Smell 62 - Flag Variables 63 Code Smell 63 - Feature Envy 64 Code Smell 64 - Inappropriate Intimacy 65 Code Smell 65 - Variables Named After Types 66 Code Smell 66 - Shotgun Surgery 67 Code Smell 67 - Middle Man 68 Code Smell 68 - Getters 69 Code Smell 69 - Big Bang (JavaScript Ridiculous Castings) 70 Code Smell 70 - Anemic Model Generators 71 Code Smell 71 - Magic Floats Disguised as Decimals 72 Code Smell 72 - Return Codes 73 Code Smell 73 - Exceptions for Expected Cases 74 Code Smell 74 - Empty Lines 75 Code Smell 75 - Comments Inside a Method 76 Code Smell 76 - Generic Assertions 77 Code Smell 77 - Timestamps 78 Code Smell 78 - Callback Hell 79 Code Smell 79 - TheResult 80 Code Smell 80 - Nested Try/Catch 81 Code Smell 81 - Result 82 Code Smell 82 - Tests Violating Encapsulation 83 Code Smell 83 - Variables Reassignment 84 Code Smell 84 - Max < Min (Javascript) 85 Code Smell 85 - And Functions 86 Code Smell 86 - Mutable Const Arrays 87 Code Smell 87 - Inconsistent Parameters Sorting 88 Code Smell 88 - Lazy Initialization 89 Code Smell 89 - Math Feature Envy 90 Code Smell 90 - Implementative Callback Events 91 Code Smell 91 - Test Asserts without Description 92 Code Smell 92 - Isolated Subclasses Names 93 Code Smell 93 - Send me Anything 94 Code Smell 94 - Too Many imports 95 Code Smell 95 - Premature Classification 96 Code Smell 96 - My Objects 97 Code Smell 97 - Error Messages Without Empathy 98 Code Smell 98 - Speling Mistakes 99 Code Smell 99 - First Second 100 Code Smell 100 - GoTo 101 Code Smell 101 - Comparison Against Booleans 102 Code Smell 102 - Arrow Code 103 Code Smell 103 - Double Encapsulation 104 Code Smell 104 - Assert True 105 Code Smell 105 - Comedian Methods 106 Code Smell 106 - Production Dependent Code 107 Code Smell 107 - Variables Reuse 108 Code Smell 108 - Float Assertions 109 Code Smell 109 - Automatic Properties 110 Code Smell 110 - Switches With Defaults 111 Code Smell 111 - Modifying Collections While Traversing 112 Code Smell 112 - Testing Private Methods 113 Code Smell 113 - Data Naming 114 Code Smell 114 - Empty Class 115 Code Smell 115 - Return True 116 Code Smell 116 - Variables Declared With 'var' 117 Code Smell 117 - Unrealistic Data 118 Code Smell 118 - Return False 119 Code Smell 119 - Stairs Code 120 Code Smell 120 - Sequential IDs 121 Code Smell 121 - String Validations 122 Code Smell 122 - Primitive Obsession 123 Code Smell 123 - Mixed 'What' and 'How' 124 Code Smell 124 - Divergent Change 125 Code Smell 125 - 'IS-A' Relationship 126 Code Smell 126 - Fake Null Object 127 Code Smell 127 - Mutable Constants 128 Code Smell 128 - Non English Coding 129 Code Smell 129 - Structural Optimizations 130 Code Smell 130 - AddressImpl 131 Code Smell 131 - Zero Argument Constructor 132 Code Smell 132 - Exception Try Too Broad 133 Code Smell 133 - Hardcoded IF Conditions 134 Code Smell 134 - Specialized Business Collections 135 Code Smell 135 - Interfaces With just One Realization 136 Code Smell 136 - Classes With just One Subclass 137 Code Smell 137 - Inheritance Tree Too Deep 138 Code Smell 138 - Packages Dependency 139 Code Smell 139 - Business Code in the User Interface 140 Code Smell 140 - Short Circuit Evaluation 141 Code Smell 141 - IEngine , AVehicle, ImplCar 142 Code Smell 142 - Queries in Constructors 143 Code Smell 143 - Data Clumps 144 Code Smell 144 - Fungible Objects 145 Code Smell 145 - Short Circuit Hack 146 Code Smell 146 - Getter Comments 147 Code Smell 147 - Too Many Methods 148 Code Smell 148 - ToDos 149 Code Smell 149 - Optional Chaining 150 Code Smell 150 - Equal Comparison 151 Code Smell 151 - Commented Code 152 Code Smell 152 - Logical Comment 153 Code Smell 153 - Too Long Names 154 Code Smell 154 - Too Many Variables 155 Code Smell 155 - Multiple Promises 156 Code Smell 156 - Implicit Else 157 Code Smell 157 - Balance at 0 158 Code Smell 158 - Variables not Variable 159 CoDe SmElL 159 - mIxEd_cASe 160 Code Smell 160 - Invalid Id = 9999 161 Code Smell 161 - Abstract/Final/Undefined Classes 162 Code Smell 162 - Too Many Parentheses 163 Code Smell 163 - Collection in Name 164 Code Smell 164 - Mixed Indentations 165 Code Smell 165 - Empty Exception Blocks 166 Code Smell 166 - Low-Level Errors on User Interface 167 Code Smell 167 - Hashing Comparison 168 Code Smell 168 - Undocumented Decisions 169 Code Smell 169 - Glued Methods 170 Code Smell 170 - Refactor with Functional Changes 171 Code Smell 171 - Plural Classes 172 Code Smell 172 - Default Argument Values Not Last 173 Code Smell 173 - Broken Windows 174 Code Smell 174 - Class Name in Attributes 175 Code Smell 175 - Changes Without Coverage 176 Code Smell 176 - Changes in Essence 177 Code Smell 177 - Missing Small Objects 178 Code Smell 178 - Subsets Violation 179 Code Smell 179 - Known Bugs 180 Code Smell 180 - BitWise Optimizations 181 Code Smell 181 - Nested Classes 182 Code Smell 182 - Over Generalization 183 Code Smell 183 - Obsolete Comments 184 Code Smell 184 - Exception Arrow Code 185 Code Smell 185 - Evil Regular Expressions 186 Code Smell 186 - Hardcoded Business Conditions 187 ㄥ8Ɩ llǝɯS ǝpoƆ - spɹɐʍʞɔɐq ǝslƎ/ℲI 188 Code Smell 188 - Redundant Parameter Names 189 Code Smell 189 - Not Sanitized Input 190 Code Smell 190 - Unnecessary Properties 191 Code Smell 191 - Misplaced Responsibility 192 Code Smell 192 - Optional Attributes 193 Code Smell 193 - Switch Instead of Formula 194 Code Smell 194 - Missing Interval 195 Code Smell 195 - Yoda Conditions 196 Code Smell 196 - Javascript Array Constructors 197 Code Smell 197 - Gratuitous Context 198 Code Smell 198 - Hidden Assumptions 199 Code Smell 199 - Gratuitous Booleans 200 Code Smell 200 - Poltergeist 201 Code Smell 201 - Nested Ternaries 202 Code Smell 202 - God Constant Class 203 Code Smell 203 - Irrelevant Test Information 204 Code Smell 204 - Tests Depending on Dates 205 Code Smell 205 - Code in Destructors 206 Code Smell 206 - Long Ternaries 207 Code Smell 207 - Dynamic Methods 208 Code Smell 208 - Null Island 209 Code Smell 209 - Side Effects 210 Code Smell 210 - Dynamic Properties 211 Code Smell 211 - Tab over Spaces 212 Code Smell 212 - Elvis Operator 213 Code Smell 213 - Hoisting 214 Code Smell 214 - Duplicate Parameter Names 215 Code Smell 215 - Deserializing Object Vulnerability 216 Code Smell 216 - Fat Interface 217 Code Smell 217 - Empty Implementation 218 Code Smell 218 - Magic Concatenation 219 Code Smell 219 - Looping from index 0 220 Code Smell 220 - Return Tuple 221 Code Smell 221 - Missing Break in Switch 222 Code Smell 222 - Comma Operator 223 Code Smell 223 - Racial Naming 224 Code Smell 224 - Deodorant Comments 225 Code Smell 225 - Pass by Reference 226 Code Smell 226 - Mixed Priorities 227 Code Smell 227 - Cowboy Coding 228 Code Smell 228 - Multiple Classes per File 229 Code Smell 229 - Red Tape 230 Code Smell 230 - Schrödinger Code 231 Code Smell 231 - Redundant Data 232 Code Smell 232 - Reusable Code 233 Code Smell 233 - Collections Count 234 Code Smell 234 - Long Circuit 235 Code Smell 235 - Console Side Effects 236 Code Smell 236 - Unwrapped Lines 237 Code Smell 237 - Attribute Definitions 238 Code Smell 238 - Entangled Code 239 Code Smell 239 - Big Pull Request 240 Code Smell 240 - Dead Store 241 Code Smell 241- Referential Transparency Violation 242 Code Smell 242 - Zombie Feature Flags 243 Code Smell 243 - Concatenated Properties 244 Code Smell 244 - Incomplete Error information 245 Code Smell 245 - exec() and eval() 246 Code Smell 246 - Expiration Date 247 Code Smell 247 - Javascript Replace 248 Code Smell 248 - Unreliable Copy 249 Code Smell 249 - Constants as Numbers 250 Code Smell 250 - Premature Memoization 251 Code Smell 251 - Collections Empty 252 Code Smell 252 - NullCustomer 253 Code Smell 253 - Silent Truncation 254 Code Smell 254 - Mystery Guest 255 Code Smell 255 - Parallel Hierarchies 256 Code Smell 256 - Mutable Getters 257 Code Smell 257 - Name With Collections 258 Code Smell 258 - Secrets in Code 259 Code Smell 259 - Testing with External Resources 260 Code Smell 260 - Crowdstrike NULL 261 Code Smell 261 - DigiCert Underscores 262 Code Smell 262 - Not Replaced Constants 263 Code Smell 263 - Squatting 264 Code Smell 264 - Hanlon's Razor 265 Code Smell 265 - Linguistic Confusion 266 Code Smell 266 - Collection Aliasing 267 Code Smell 267 - Objects Aliasing 268 Code Smell 268 - Ternary Metaprogramming 269 Code Smell 269 - Low-Level Addition 270 Code Smell 270 - Boolean APIs 271 Code Smell 271 - The Hollywood Principle 272 Code Smell 272 - API Chain 273 Code Smell 273 - Overengineering 274 Code Smell 274 - Cascaded Returns 275 Code Smell 275 - Missing Test Wrong Path 276 Code Smell 276 - Untested Regular Expressions 277 Code Smell 277 - UPPERCASE Acronyms 278 Code Smell 278 - DirName and File 279 Code Smell 279 - Loop Premature Optimization 280 Code Smell 280 - Spaghetti Code

We need to make some changes. We need to be clear on why

TL;DR: Be declarative on your design or implementation decisions.

Problems

Code Comments
Lack of testability

Solutions

Be Explicit about the reasons.
Convert the comment to a method.

Context

Sometimes we find arbitrary rules not so easily testable.

If we cannot write a failing test, we need to have a function with an excellent and declarative name instead of a comment.

Sample Code

Wrong

// We need to run this process with more memory
set_memory("512k)

run_process();

Right

increase_memory_to_avoid_false_positives();
run_process();

Detection

[X] Semi-Automatic

This is a semantic smell.

We can detect comments and warn us.

Conclusion

Code is prose. And design decisions should be narrative.

Relations

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

Code Smell 75 - Comments Inside a Method

Maxi Contieri ・ Jun 5 '21

#codenewbie #tutorial #oop #programming

Disclaimer

Code Smells are just my opinion.

Credits

Photo by Goh Rhy Yan on Unsplash

Programs, like people, get old. We can’t prevent aging, but we can understand its causes, limit its effects and reverse some of the damage.

Mario Fusco

Software Engineering Great Quotes

Maxi Contieri ・ Dec 28 '20

#codenewbie #programming #quotes #software

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code

Maxi Contieri ・ May 21 '21

#codenewbie #tutorial #codequality #beginners

Code Smells (280 Part Series)

Top comments (2)

Create template

Templates let you quickly answer FAQs or store snippets for re-use.

Dismiss

Joe Mainwaring

20+ years across IT and Engineering. Founding Partner at Super Pax. I author Senior, Principal, and Executive-level technology posts.

Location

Chicago, IL
Education

Western Michigan University
Joined

Feb 22, 2018

• Oct 12 '22

Copy link

I thought this article was going to focus on establishing ADRs over simply renaming functions as documentation

Maxi Contieri

Learn something new every day. - I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.

Location

Buenos Aires
Education

Computer Science Degree at Universidad de Buenos Aires
Pronouns

He/Him
Work

Senior Software Engineer at Avature
Joined

Apr 13, 2020

• Oct 12 '22

Copy link

you mean architectural decision record?
is that decision on code or on external sources?

Code of Conduct • Report abuse

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink.

Hide child comments as well

For further actions, you may consider blocking this person and/or reporting abuse

DEV Community