Idioms and Coding Standards

Clean Code Principles for Squeak

Formatting

• PrettyPrint: Most formatting issues can be resolved by switching to prettyPrint in the System Browser. This auto-formats spacing, indentation, and removes unnecessary brackets. It does not change the semantics of the code, only the formatting. Note that it may not handle inline comments well; consider keeping all comments at the top of the method or class.

Code Style

in most cases this is handled by prettyPrint

• No Dot at the End: Avoid placing a period (.) at the very end of functions or methods.
• Non-defensive Brackets: Use brackets only when necessary to clarify precedence. Overuse can make code harder to read.
• Space Between Operands and Values: Ensure there is a space between operators and their operands for readability. For example, a + b instead of a+b.

Naming Conventions

• Meaningful Names: Method and variable names should be descriptive and convey a clear purpose. Avoid single-letter names except for common counters like i or j.
• Standard Instance Name: The standard variable name for a class instance is aClassInstance.

Comments

• Class Comments: Provide comments for classes to explain their purpose. This helps others (and future you) understand the intent behind the code.
• Method Comments: Include comments at the top of methods to describe their behavior, especially if the method's purpose is not immediately clear. Only add a comment if it adds value for the reader.

Best Practices

• Magic Numbers: Replace magic numbers with named constants or class-side variables to improve readability and maintainability.
• Use Cascades: Prefer using cascades when possible to make the code more concise and readable.
• If-Statement Guide: Simplify if-statements by using guard clauses and ensuring that each branch is easy to read. For example, handle special cases or errors first and then proceed with the main logic.
• Static Methods: Methods that do not depend on the instance (self) should be defined as class methods.

Additional Guidelines

• Single Responsibility Principle: Ensure each method or class has a single responsibility or purpose. This makes the code easier to understand and maintain.
• Avoid Deep Nesting: Avoid deep nesting of blocks or conditionals. Refactor nested code into smaller methods to improve readability. See Best Practices
• Consistent Indentation: Use consistent indentation (spaces or tabs) throughout the codebase. Configure your editor to help enforce this. See Formatting
• Limit Line Length: Keep line lengths reasonable, ideally under 80 characters, to enhance readability. (Or a default-sized window)
• Avoid Global State: Minimize the use of global variables. Encapsulate state within classes or objects.
• Code Reviews: Regularly conduct code reviews to catch issues early and ensure adherence to coding standards. See Git
• Refactoring: Regularly refactor code to improve its structure and readability. Remove dead code and simplify complex methods.
• Error Handling: Implement robust error handling. Ensure that exceptions are caught and handled appropriately to avoid crashes. Note: this is still a TODO