Best Coding Practices
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
Avoid repetition whenever possible
- DRY - Do Not Repeat Yourself
- DIE - Duplication is Evil
- Abstract duplicate code into a function
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~)
When the best coding practices are followed, youโll be able to create uniform code that is reusable by other engineers and developers sharing the same codebase. The last step is to test your code for unusual cases, so it can handle exceptions quickly and go over the rest of the syntax.
If you choose to input hundreds of commands from a script, the computer needs to understand every line before it can carry out the desired tasks. This includes actions like uploading a PDF document or displaying a userโs chat history.
Learning to write cleaner code is an essential skill to master for every aspiring magician.
Exercises[edit]
- M1297-28 Complete Merlin Mission Manager Mission M1297-28.
References[edit]
- API Design Guidelines (Swift Documentation)
- API Style Guidelines (Google Documentation)