You are here because you code, but how professional does your code look? Professional programmers think of systems as stories to be told rather than programs to be written.
I have listed 17 important clean coding standards into 4 different sections. Make sure you bookmark the page and share it with your colleagues:
- The name of a variable, function, or class should answer all the big questions. It should tell you why it exists, what it does, and how it is used.
- Best to use Computer Science terms (algorithm names, pattern names, math etc.) wherever possible. Otherwise, stick with application domain terms. Do not try to be cute or funny when naming. Spend your time wisely when trying to find the correct name.
- Shorter names are generally better than longer ones, as long as they are clear. Add enough context to a name, but NO MORE.
Functions and Methods
- FUNCTIONS SHOULD SERVE ONE PURPOSE. They should serve it well with NO SIDE EFFECTS. This means one level of abstraction per function.
– They can’t be divided reasonably into sections.
– They can’t do anything hidden. If you must have some coupling, then you should AT LEAST make it clear in the name (ex: serializeAndSetContext(…), startThreadAndLogWork(…)). Although this isn’t that pretty.
- Should be small. Hardly ever longer than 30 lines.
- Blocks within IF, ELSE, WHILE, FOR should be small, one line in an ideal world. And that should probably be a function call.
- The indent size within a function shouldn’t be greater than 2, rarely 3. If you come up with 3 levels, first consider if it is possible to break into another function.
- Arguments are hard for testing. Ideal number of arguments for a function is niladic(0). Next comes one monadic, followed closely by dyadic. More than 3 arguments require special treatment, most likely those arguments need to exist in a class of their own.
- In professional programming, you have only 2 reasons for function arguments: asking a question or operating on arguments (transforming it, returning a dependent result).
- In professional programming, flag arguments are bad practice. Passing a bool into a function proclaims that the function does more than one thing. It does one thing if the flag is true and another if the flag is false.
- In monadic argument functions, we should keep a verb phrase + name pair: download(object), convertToString(date) etc.
- Comments are, at best, a necessary evil. Most of them are excuses/ justification for bad code. C. Martin: “Comments usually compensate failure to express ourselves in code.“
- Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.
- TODO comments are acceptable. But the TODO should be addressed when possible.
- Use the newspaper metaphor for source code: You read it vertically. At the top you expect a headline that will tell you what the story is about and allows you to decide whether it is something you want to read.
- If one function calls another, they should be vertically close, and the caller should be above the callee, if at all possible.
- Surround assignment operators with white space to accentuate them.
(Note: I participate in the affiliate amazon program. This post may contain affiliate links from Amazon or other publishers I trust (at no extra cost to you). I may receive a small commission when you buy using my links, this helps to keep the blog alive! See disclosure for details.)
Want to learn more? Grab your Clean Code Handbook:
This is a personal blog. My opinion on what I share with you is that “All models are wrong, but some are useful”. Improve the accuracy of any model I present and make it useful!