rewrite style guide #1
Conversation
| - Scope size correlates to amount of possible interactions (in a scope, the reader must assume that any two elements can interact). | ||
|
|
||
| Therefore perhaps the only objective metric by which a design can be examined is code length. | ||
| - Bug occurrence is correlated with amount of code. The more code you write, the more bugs you create. |
There was a problem hiding this comment.
@nitzo do you agree with those 3 lines?
|
|
||
| Some forms of duplication are easy to spot, simply by the noisy feeling you get reading them. | ||
| Put your core logic at the center, and remove "fluff" code that might confuse the reader. |
There was a problem hiding this comment.
Not sure I agree with this statement.
|
|
||
| Code reviews are a great tool to enhance code quality and stability. It works like this: | ||
| ## Before we start, some values |
There was a problem hiding this comment.
I would expect something more broad and a bit less opinionated.
I would expect a general guideline covering things below and then a specific guideline for Python and JS. There general rules on how we code that are language agnostic.
Function and Method Guidelines:
Provide best practices for writing functions and methods, including rules on function length, single responsibility principle, and error handling.
Error Handling:
Specify how to handle exceptions and errors in a consistent manner across the codebase.
Code Styling:
which tools we use for code styling
Testing Guidelines:
If applicable, include guidelines for writing unit tests and test case naming conventions. Encourage developers to write testable and modular code.
Security Considerations:
Address security-related coding practices, such as handling user input, avoiding SQL injection, and preventing common vulnerabilities.
Performance Guidelines:
Provide guidelines for writing efficient code and avoiding common performance pitfalls.
Code Reviews:
Outline the code review process and expectations. Mention the roles and responsibilities of team members during code reviews.
Integration and Deployment:
If relevant, include guidelines for integrating code into the main branch and deploying to production environments.
Frameworks and Libraries:
If your project uses specific frameworks or libraries, provide guidelines on how to use them effectively and consistently.
Deprecated Code and Legacy:
Address how to handle deprecated code and legacy systems while maintaining code quality.
Error Messages and Logging:
Specify guidelines for writing clear and informative error messages and setting up logging practices.
Consistency Over Personal Preference:
Emphasize the importance of consistency over personal coding preferences, encouraging developers to adhere to the agreed-upon style guide.
|
|
||
| If a function starts with some logic of when the core logic should occur, factor this logic out. | ||
| Make sure every word in the function name is meaningful. Therefore, words like ```get```, ```run```, ```process```, ```make```, ```handle```, ```do``` can most times be removed or replaced with a more specific verb like ```fetch```, ```read```, ```load``` etc. |
|
I do find this style guide strongly opinionated (even with the removals). I do wonder if we should focus on clear principles but give people a bit more room and avoid code review comments on things that, to me, are not really important. For example: I have never seen a style guide that goes into those details. This is a very good example (nothing on naming conventions): |
No description provided.