Writing bad code is like showing up late to a job interview poorly dressed and telling the interviewer that he or she is an idiot. If you don’t care enough about your code to write it well, why in the world should anyone care to read it?
“Nothing can be quite so helpful as a well-placed comment. ... Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.” — Robert C. Martin
- Prefer code that says what it means to code that needs comments.
- Use comments to clarify things that cannot be said in the code, such as the intent (but never the inner workings) of a non-trivial, dense, or cryptic block of code.
- A comment at the very top of a file that tells the reader the purpose of the file may be useful.
- Where required, licenses and copyright notices can appear in comments.
- You can use a comment to say who helped you with some code, whose bright idea led to the code, or a hyperlink to the source of the idea or algorithm behind the code.
- Comments should always be at a level of abstraction above the code; they must never “repeat the code.”
- Think twice before commenting a function or method. Maybe you should pick a really good descriptive name for the function instead. Still thinking of that comment? Try a better name.
Not writing unit tests is not an option.
- Write unit tests properly. Printing is for debugging, not testing.
- Cover all boundary cases and potentially troublesome cases: empty, zero, negative, full, huge numbers, etc.
Formatting and Naming
Sloppy formatting shows you don’t give a crap about yourself. Perhaps you are just as careless with your personal hygiene or personal finances?
- Don’t ever be inconsistent with indentation, spacing or capitalization.
- Don’t mix camel case and underscores within the same identifier class; again, consistency is paramount.
- It is best to always save code with spaces, never tabs, because when someone else reads your code with tabs it will often look disgusting.
- Names should be pronouncable. Don’t use partial abbreviations like pnt for point, or nbr for number, or WndMgr for WindowManager.
- Only abbreviate if you have a loop variable, a parameter or local variable with tiny scope or a well-accepted and understood acronym.
Excessive copy-paste shows you don’t give a crap about yourself.
- One fact in one place: a simple change should not require you to make multiple edits.
- Don’t hardcode data that is supposed to be algorithmically generated.
- Don’t use hardcoded literals, sometimes called
except for things like 0, 1, and sometimes 2.
- However, you do not have to be "as DRY" in unit tests! Being
DAMP is sometimes better
Efficiency and Security
Sometimes a readability versus performance tradeoff pops up, but quite often the most
readable code actually is the most efficient. And sometimes, your code may be
prone to efficiency attacks, so watch out.
- Don’t call functions (like
strlen, say) over and over again if they will always be returning the same result. If you need the result of a function call more than once, cache it.
- Watch out for functions that would take forever if passed huge numbers.
- Make sure your code is resilient for all inputs. Don’t let your application crash ungracefully. Detect malicious inputs. Never trust anyone.
- Don’t write code that accumulates roundoff errors.
- Always check for
null before dereferencing a pointer. If you ever use
-> in C), ask yourself whether there is any way the pointer can be null.
Often, compact code is more readble than drawn-out code.
C is hard, but if you keep some things in mind, you can avoid the common problems.
- Match your mallocs and frees.
- When writing a opaque data structure module, remember to include a
- Remember to leave space for the zero byte at the end of a string.
- Never do a
strcpy of a passed in string into a fixed-size local string variable.
- Never use
- In general, never assume your buffer is big enough.