Clean Code Guidelines

In order to archive a consistent code style we set up this document to have a common understanding of how we write clean code:

Naming

• Choose descriptive names for objects, variables and methods
• Capitalize class names, global variables, pool dictionaries, and class variables
• Do not capitalize instance and temporary variables, parameters, and methods
• All Names should be in Camel-Case, Parameter-Names should start with a or an (e.g. aChatListItem)
• Temporary variables don't use a
• Do not use hard-coded (magic) numbers in an expression
• Acronyms like JSON or ID are spelled like Json and Id in the code

Comments

• Code should be self-documenting!
• Avoid comments that restate the code
• In general don't write Comments, only in very rare cases

Formatting

• Insert one blank line after the method name
• Insert a dot at the end of a method if it is not a return statement
• Employ at least one blank before and after a binary selector
• Leave spaces around @
• Leave one blank before a left parenthesis and after a right parenthesis
• Leave one blank after but not before a comma, a semicolon, and a colon in a selector
• Put zero or one argument messages on the same lines as their receiver
• For messages with two or more keywords put each keyword / argument pair on its own line, indented one tab
• Use a Cascade to send several messages to the same receiver
• Only use parenthesis if necessary
• For blocks do objects do: [:anObject | anObject delete].
• Leave no trailing whitespaces at the end of lines or after the method
• Leave no two consecutive empty lines in a method

Instance Variables

• Only set and read instance variables by accessor methods
• Accessor methods should have no other side effects, if you want side effects add an extra method, that calls the accessor and executes side effects
• Try to limit the number of instance variables to less than ten, except for data-classes modeling the Telegram database
• Put default values into a category default values on the class side and use self class default<ValueName> to get them

Misc.

• Use blocks instead of Symbols for methods like aCollection do:
• Always think about using when:send:to: for communication between core and UI
• To mark a method as a known failure (e.g. for Base64 images), write "@linter-ignore" as a comment on the second line of the method. All such methods will be ignored by linter tests that use methodLinesDo. That does not include all linter tests though.
• Always put the expected value first in your asserts to generate helpful messages for nil. Example: self assert: TCTMMocks mockUsername equals: uut username