Comment As You Code To Make Sure You Understand the Problem Domain Well-Enough [DC1] [WHAT]

Writing comments before jumping into coding can help you outline a design and think through potential pitfalls before going through the more expensive effort of writing a ton of code. It’s cheaper to change comments if you discover a problem than a bunch of code.

The following steps show how you can integrate commenting early on in your development process to facilitate understanding the problem before diving into heavy coding. These steps are focused on designing a function, but similar steps can be applied to many other parts of code:

1. Draft an initial function signature.

   1. If possible, it’s fine to write function header documentation (the next step) before this one, so feel free to interchange these steps. Many programmers may find it easier to at least stub out an initial function signature first, which is why this step is listed first.

2. Write function header documentation.

3. Revise the function signature (if needed).

4. Write MAJOR comments to outline the major steps for the function.

5. Write minor comments to fill in any details you’re already aware of.

6. Iterate on the comments until you’re happy.

7. Write code for the function!

The following examples show how comments can be laid out before code even starts being written:

If you’re having trouble commenting, that’s a warning sign that you don’t understand the problem well-enough. Circle back to make sure you understand the problem well-enough to comment on it. That time is well-spent, and the time “commenting” is really time spent understand the problem you need to tackle, which will result in better and simpler code.