Expand Clean Code Section #106
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
icottiero
requested changes
Nov 20, 2024
Comment on lines
+7
to
+60
| Image above is a pretty good explanation on how to distinguish between good and bad code. It is WTF/s, and almost every code will have it, but good code will make your colleagues less mead, software easy to manage and grow, and enable the company to evolve. | ||
|
|
||
|
|
||
| To develop code that will put us on the left side of the above image, developers should always strive to apply a set of principles, patterns and well-known best practices. | ||
| To develop code that will put us on the left side of the above image, developers should always strive to apply a set of principles, patterns and well known best practices. | ||
|
|
||
|
|
||
| ### Clean code reflects in : | ||
| * Elegant, efficient and simple to read code. | ||
| * It is self-explanatory, and logic is straightforward, without the need for explanatory comments. | ||
| * It favors exception throwing instead of error codes and has complete and centralized error handling. | ||
| * It is self-explanatory, logic is straightforward, without the need of explanatory comments. | ||
| * If favors exception throwing instead of error codes, and has complete and centralized error handling. | ||
| * It should reflect SOLID principles, especially single responsibility. | ||
| * It does not contain code duplications across modules and multiple projects. | ||
| * It favors composition over inheritance (does not contain class explosion) and utilizes design patterns. | ||
| * It is easy to test. | ||
| * It is well formatted. | ||
| * It follows well-defined naming conventions and the coding style is consistent. | ||
| * Classes tend to be small and methods do not have a long list of input parameters. | ||
| * It is well (and consistently) organized on the directory, project and solution levels. | ||
| * It follows well defined naming conventions and coding style is consistent. | ||
| * Classes tend to be small and methods does not have long list of input parameters. | ||
| * It is well (and consistiently) organized on the directory, project and solution level. | ||
|
|
||
|
|
||
| ### Naming | ||
|
|
||
| Developers write code for machines to execute it, but for other developers to maintain and extend it. So code should be easy to read and understand. | ||
| The code should reflect the shared vocabulary used by all team members involved in the project. | ||
| Developers write code for machines to execute it, but for other developers to maintain it and extend it. So code should be easy to read and understand. | ||
| Code should reflect shared vocabulary used by all team members involved in the project. | ||
|
|
||
| So in general naming should be: | ||
|
|
||
| * Well thought through, and should reflect business concepts and rules. | ||
| * Consistent through the software. | ||
| * Truthful - this applies especially on the method level, where the method name should not be too general or misleading due to the method's side effects. | ||
| * Truthful - this applies especially on the method level, where method name should not be too general or misleading due to method's side effects. | ||
|
|
||
|
|
||
| ### Comments | ||
|
|
||
| Comments are part of the source code, and if not consisted of significant info, then comments act as noise. Even worse, if not well maintained they can lead developers to false conclusions. In general, developers should avoid writing comments. If the code is unclear, it is a sign it should be rewritten. | ||
| Comments are part of source code, and if not consisted of significant info, then comments act as noise, and even worse if not well maintained they can lead developers to false conclusions. In general, developers should avoid writing the comments. If the code is unclear, it is a sign it should be rewritten. | ||
|
|
||
| Exceptions: | ||
|
|
||
| * Describing an example | ||
| * Pointing to resources in the documentation | ||
| * Pointing to resources in documentation | ||
| * Todos | ||
| * Swagger documentation | ||
|
|
||
|
|
||
| ### Methods | ||
|
|
||
| Methods should be short and have a single responsibility. | ||
| The logic contained in a single method should reflect the same level of abstraction. Mixing different levels of abstraction in the same function is a code smell. | ||
| Methods should be short and have single responsibility. | ||
| Logic contained in a single method should reflect the same level of abstraction. Mixing different levels of abstraction in the same function is a code smell. | ||
|
|
||
| * Methods should not have side effects, and method names should reflect exactly what they are doing. | ||
| * Prefer methods no longer than 10 lines. | ||
| * The number of input parameters should be up to 4. If there is a need for more parameters, consider creating a DTO. | ||
| * Number of input parameters should be up to 4. If there is a need for more params, consider creating a DTO. | ||
| * Methods should not have multiple return params (exception is TryDoSomething pattern which returns bool and resulting object via out param). | ||
| * Avoid using flag arguments. Split the method into several independent methods that can be called from the client without the flag. | ||
| * Avoid using flag arguments. Split method into several independent methods that can be called from the client without the flag. |
There was a problem hiding this comment.
I wanted to target the whole document, but couldn't, so apply this comment to everything above the changes you added - can you please double-check all the changes here? It seems like you might have branched out on an older version of the doc, I remember working on these changes, but in the other direction :)
There was a problem hiding this comment.
I checked line by line on master and staging, it seems like these changes you pointed out aren't there... I know that I didn't add them, I only added the SOLID principles :D But since they aren't present on staging and typos are removed with them, should we keep the changes anyway?
StanojevicDanilo
force-pushed
the
feature/T-951-clean-code-expansion
branch
from
c73172b to
e400a44
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Clean Code - expand the chapter