Always try to take pride in your work. Here are just a few things that can help you do just that.
“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 (but not always) 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. Always be a good citizen and give attribution!
- 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 can be construed as being lazy, or not taking pride in yourself or your work. Your code should, in addition to being correct, look beautiful. It should read, in the words of Grady Booch, “like well-written prose.”
- 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 pronounceable. Don’t use partial abbreviations like pnt for point, or nbr for number, or WndMgr for WindowManager.
- Parts of speech matter. Be very careful to use nouns for things and properties, verbs for actions, and so on.
- Only abbreviate if you have a loop variable, a parameter or local variable with tiny scope or a well-accepted and understood acronym.
Note that the use of a linter or code prettier can check for these items and more, and generally automatically fix any problems. Once you have learned the basics of programming and have gotten familiar with editing and running programs, use these tools.
So many bugs have been traced to “I remembered to change it here but not there.”
- 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
magic numbers, 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.