Difference between revisions of "Best Coding Practices"
| Line 44: | Line 44: | ||
{{BestPractice|207| | {{BestPractice|207| | ||
Always use appropriate and descriptive variable names | Always use appropriate and descriptive variable names | ||
* '' | * ''Nouns'' are usually the most appropriate for defining variables | ||
}} | }} | ||
{{BestPractice|208| | {{BestPractice|208| | ||
Always use appropriate and descriptive function names | Always use appropriate and descriptive function names | ||
* ''verbs'' are usually most appropriate | * ''verbs'' are usually the most appropriate for defining functions | ||
}} | }} | ||
{{BestPractice|394| | {{BestPractice|394| | ||
Exiting from a function in order | |||
* In general, | * In general, don’t exit a function in the middle | ||
* Only return a function value when the input satisfies a condition | |||
}} | }} | ||
{{BestPractice|444| | {{BestPractice|444| | ||
Avoid repetition | Avoid repetition whenever possible | ||
* DRY | * DRY = Do Not Repeat Yourself | ||
* DIE | * DIE = Duplication is Evil | ||
* Abstract duplicate code into a function | |||
}} | }} | ||
{{BestPractice|502| | {{BestPractice|502| | ||
Determine the appropriate scope | |||
* | * The scope should not be wider than absolutely necessary | ||
* Think about the context of your coding project | |||
* Narrow it down into specific goals | |||
}} | }} | ||
{{BestPractice|523| | {{BestPractice|523| | ||
Select the appropriate loop (for loop, while loop) to iterate over a sequence or run a block of code repeatedly. Avoid breaking out of a loop midway. | |||
}} | }} | ||
{{BestPractice|029| | {{BestPractice|029| | ||
Always use appropriate indentation | Always use the appropriate indentation | ||
* | * White space is helpful for organizing blocks of code | ||
* | * Either 2 or 4 spaces are preferable | ||
* Use the proper closing braces and parentheses to contain multiple statements | |||
}} | }} | ||
{{BestPractice|074| | {{BestPractice|074| | ||
Use comments to | Use comments to assist others in updating the code | ||
* Deliberate and helpful comments | * Don’t leave them in the dark about how it functions | ||
* Avoid | * Deliberate and helpful comments are ideal for explaining the logic | ||
* Avoid comments stating the ''obvious'' | |||
}} | }} | ||
{{BestPractice|617| | {{BestPractice|617| | ||
Add the appropriate nesting to keep errors at bay | |||
* Avoid deep nesting | * Avoid deep nesting or else the code will get buried | ||
* Avoid inappropriate nesting of functions | * Avoid inappropriate nesting of functions that may cause confusion | ||
* Indent correctly according to | * Indent correctly according to the level of nesting | ||
}} | }} | ||
{{BestPractice|831| | {{BestPractice|831| | ||
Limit line length | Limit the horizontal line length. Vertical lines are easier to scan. | ||
}} | }} | ||
{{BestPractice|907| | {{BestPractice|907| | ||
Organize files appropriately | Organize the class files appropriately. Generally, one class per file is sufficient. | ||
}} | }} | ||
| Line 105: | Line 108: | ||
Hardcode only when there is no other choice | Hardcode only when there is no other choice | ||
* All other values should be one of the following: | * All other values should be one of the following: | ||
** Calculated | ** Calculated in advance | ||
** Retrieved from configuration | ** Retrieved from configuration | ||
}} | }} | ||
{{BestPractice|959| | {{BestPractice|959| | ||
Do not place extraneous files into source control | Do not place extraneous files into the source control | ||
* Exclude all build artifacts | * Exclude all build artifacts | ||
* Exclude | * Exclude all "backup" files (e.g. main.swift~) | ||
}} | }} | ||
Revision as of 17:27, 17 February 2023
Introduction to General Coding Standards
Coding standards are the rules and techniques for writing clean, more readable, and maintainable code in a programming language.
Think of it like casting a spell inscribed on a magic book. The book represents a style guide on formatting the code to make sure it is efficient and free of errors. The spell is the operation being executed by the interpreter according to a set of instructions. Test it out for yourself by right-clicking on “inspect” to catch a glimpse of the markup on a webpage.
While different industries have their own standards, there are universal rules for documenting code you should follow to preserve its integrity and scalability. When learning to code, the key concepts are naming, commenting, indenting, debugging, scoping, and testing.
What are the most important coding conventions?
Flowcharts depict the information flow of an algorithm. For planning multi-step functions, flowcharts are your friend.
Use the appropriate capitalization on names:
- Types and protocols (Ex: classes, objects) are UpperCamelCase (Pascal case)
- Everything else is lowerCamelCase (Ex: variable, function, method)
For code readability, clarity is more important than brevity
- Avoid long lines at all costs
- Can someone else understand what it does?
Preconditions are your friend:
- They assert the state of a program before an execution
- Include sufficient information for the message to be useful
Great functions exhibit three vital properties:
- They are easy to read and comprehend
- They are easy to debug if something goes wrong
- They are easy to modify for solving a variation of the original task[1]
Don’t declare variables outside of functions
- Global variables are evil: They cause unintentional changes to the program.
Always use appropriate and descriptive variable names
- Nouns are usually the most appropriate for defining variables
Always use appropriate and descriptive function names
- verbs are usually the most appropriate for defining functions
Exiting from a function in order
- In general, don’t exit a function in the middle
- Only return a function value when the input satisfies a condition
Determine the appropriate scope
- The scope should not be wider than absolutely necessary
- Think about the context of your coding project
- Narrow it down into specific goals
Select the appropriate loop (for loop, while loop) to iterate over a sequence or run a block of code repeatedly. Avoid breaking out of a loop midway.
Always use the appropriate indentation
- White space is helpful for organizing blocks of code
- Either 2 or 4 spaces are preferable
- Use the proper closing braces and parentheses to contain multiple statements
Use comments to assist others in updating the code
- Don’t leave them in the dark about how it functions
- Deliberate and helpful comments are ideal for explaining the logic
- Avoid comments stating the obvious
Add the appropriate nesting to keep errors at bay
- Avoid deep nesting or else the code will get buried
- Avoid inappropriate nesting of functions that may cause confusion
- Indent correctly according to the level of nesting
Limit the horizontal line length. Vertical lines are easier to scan.
Organize the class files appropriately. Generally, one class per file is sufficient.
Hardcode only when there is no other choice
- All other values should be one of the following:
- Calculated in advance
- Retrieved from configuration
Do not place extraneous files into the source control
- Exclude all build artifacts
- Exclude all "backup" files (e.g. main.swift~)
Exercises[edit]
- M1297-28 Complete Merlin Mission Manager Mission M1297-28.
References[edit]
- API Design Guidelines (Swift Documentation)
- API Style Guidelines (Google Documentation)
