Channels ▼


Coding Conventions: Make Them Agile

4. Document Your Code

As my wife says to me, people don't know what you're thinking--you have to tell them. You can't always see the logic behind a particular piece of code from the code itself. Unless you're a mind-reader.

Always document your design, implementation, and assumptions. Think of the poor developer who will inherit your code two years from now. He won't know that you intentionally passed bad parameters to that Win32 API function to take advantage of some undocumented, but badly needed API functionality.

Code that's difficult to maintain might as well be a bug.

Keep the documentation up to date. It may cost time to write clear, concise, and correct documentation, but this time will be made up in debugging and maintenance mode. If you let your documentation get out of date, it'll be harder for future developers to understand the code and work through all the design/implementation assumptions made. You also run the risk the code will just get re-written by the maintenance team because they couldn't understand what it was trying to do, which might introduce new bugs.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code, refer to rule number 10.

5. Keep Security In Mind

Check your routine's input for length and correctness (and content, if required). Make sure you read the documentation for the function you're going to call for deprecation or security warnings. If a more secure version exists, use it!

Taking these extra few moments to secure your code saves time and money down the road. More importantly, it saves your company's reputation, and maybe even your job.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs, refer to rule number 10.

6. Work In Increments

Don't try to write the entire feature or user story in one fell swoop. If possible, break your feature into increments that could be coded in a single day. This helps enforce a simple design, increasing correctness and maintainability while making it easier for reviewers (see rule 8) to understand the problem and solution.

When you break your feature into one-day increments, aim for complete code. Complete code doesn't mean finished code. The key is to produce code that could be introduced into the code base without causing regression errors.

If you leave part of a feature to be implemented later, mark it using a tag that is common to the whole team. It's then easier to realize/identify what's left to do. At Macadamian, we add a comment with the "TODO" prefix.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs, in one big patch, refer to rule number 10.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.