Why do we need this section?
There is little here that is not well accepted. These definition of coding guidelines are not opinionated
They exist so that when doing coding reviews there should be no ‘well I like a method with 50 lines in it, I think it is clearer’. Whether or not that method with 50 lines in it is actually better for the author, it does not meet these coding guidelines, and thus should be rejected in a coding review.
General Coding Guidelines
- Keep functions / methods / procedures short.
- Don’t repeat yourself: code should express a fact in one and only one place
- Look for ways to reduce the amount of complexity in code, which often but not necessarily means the most concise code.
- Learn how to use the standard libraries in the language you code in
- Refactor and reduce the code size of a function / method / procedure right after you’ve written it.
- You should strive to make your code read as though you were explaining it to a developer sitting next to you
- In a project similar problems should be solved in a similar way
- Avoid writing your own multi-threaded code. Use a library
Finally don’t let dogma get in the way of readability. This isn’t an excuse to ignore the above points and should affect only a tiny percentage of your code
Preferred programming styles
This policy does not yet cover languages like COBOL. It recommends Functional Programming over Object Orientated and states that actors should be avoided if possible.
- Good Functional Programming Code
- Good Object Orientated Code
- Actors are to be avoided for all but the very lowest of low level code, which we probably shouldn’t be writing
Meta principles
| Principle | Reason |
|---|---|
| Don’t Repeat Yourself | This is a core principle in good code. A fact should be expressed in the code in one and only one place |
| Resisting pressure | It is your job to exercise engineering judgment and balance delivering requirements against keeping the code base clean. |
| YAGNI | You ain’t going to need it. Don’t over engineer ‘just in case’ or because ‘we know we are going to need it’ |