views:

190

answers:

5

I find it very hard to answer question like : "why did you implemented it this way?" or "what's the reason of using that instead of that?" usually because the implementation is the result of a long thought process and trials and errors. By the time i'm finished i can't recall every specific details.

I wanted to know if you have some tips to keep track of your thought process and answer those question easily.

+1  A: 

"why did you implemented it this way?" or "what's the reason of using that instead of that?"

The simplest solution would be to comment your code as you write it, not as an afterthought. Your comments should include why specific approaches were taken, when you aren't taking the most obvious approach.

Mark Rushakoff
+1  A: 

I try to make the answer evident in the code itself:

"Why? Because, this way, it works correctly! And, it's easy to understand!"

Apart from that, comments in the code.

I fid it harder to document what the code is supposed to do (i.e. its functional spec.) than it is to document how it's implemented.

ChrisW
That might be because the better you specify what code should do, the easier it is to properly implement the specification. :)
Joren
That's true. Another reason (particular to me) is that I'm developing (specifying and implementing) the documentation tool that I want to use: but I can't use it because it isn't implemented yet.
ChrisW
+3  A: 

Do not rely on your memory. You have to document it to keep track of it. Aside from writing comments, you can create document to recall each and every process on the code. You can start from a brief algorithm. The advantage of this is when you are working on a team, team will not find difficult time to understand how your code is working. You can use the team as your metrics. If they understand it better, then less you worry that you wouldn't able to explain your code in future inquiry.

kratz
+1  A: 

The difficulty of recording/recalling a thought process is the main reason why "If it ain't broke don't fix it" is such a useful rule.

Commenting the entire reasoning is difficult as well. And comments typically decay over time.

The only sure fire way is to reflect the reasoning in your tests. If you chose solution C over more obvious solutions A and B for a reason, your test should be designed so that A and B fail, but C succeeds.

Neil N
How about performance considerations? Both solutions would succeed in test.
NomeN
@NomeN, thats a good question, and I don't have a really good answer. I guess I would have to make one of the tests a load test. But really it depends on the situation.
Neil N
A: 

I keep a work log or journal, and use it to record what I am doing and to think "out loud".

When I am working on Windows I use Keynote which lets you combine tabbed pages and tree outlines in a flexible way. On Linux I use plain text in Vim, sometimes in conjunction with the Vim Outliner plugin.

This is a habit I have had for the last couple of decades of programming - I used to use a pen & paper journal, but the ability to instantly search through years of notes makes a computer based system invaluable.

Dave Kirby