4 ms·

My take away from the interview was "You should comment code before you write it." I am going to try it on my code and see how it works out.

by jinx 18y ago

gustavo_duarte 18y ago
Steve McConnell advocates a similar thing in Code Complete 2, which he calls Pseudocode Programming Process, PPP. The idea is that when first creating a method or function, you write out in comments what you're going to do in a 'why' level (eg, 'keep track of resources') rather than a 'how' level (eg, 'increase cntFooBar by 1'). You then start 'filling out' the code to do what you 'designed' via the comments. Hopefully you end up with a better designed routine, and you get free comments to boot as they now explain what the code is doing. When I first read Code Complete as an impressionable teenager I tried it out and liked it, but I have since had a change of heart on this issue and other Code Complete wisdom. I rarely comment inside methods anymore.
- derefr 18y ago
  > You then start 'filling out' the code to do what you 'designed' via the comments. Another approach is to just drop the comment markers entirely, massage the pseudocode until it's valid syntax, and then write a DSL that does the right thing upon its execution. That way, all you ever really have is comments.
gaius 18y ago
This is called 'literate programming'.
etal 18y ago
It is a good approach. The PLT Scheme textbook How to Design Programs walks you through a process for writing new code that more or less goes like that: 1. Write a comment describing the problem. 2. Write comments describing the form of all the data structures involved in the problem, and turn those comments into data definitions. 3. Then write a comment describing the input and output of a function, write the function header, use the form of the data structures defined above to sketch a function body with comments and a few bits of code; repeat for each operation. 4. Finally, fill in the gaps -- at that point it's almost obvious how each function should be written.

My take away from the interview was "You should comment code before you write it." I am going to try it on my code and see how it works out.

by jinx 18y ago

My take away from the interview was "You should comment code before you write it." I am going to try it on my code and see how it works out.

gustavo_duarte 18y ago

Steve McConnell advocates a similar thing in Code Complete 2, which he calls Pseudocode Programming Process, PPP. The idea is that when first creating a method or function, you write out in comments what you're going to do in a 'why' level (eg, 'keep track of resources') rather than a 'how' level (eg, 'increase cntFooBar by 1'). You then start 'filling out' the code to do what you 'designed' via the comments. Hopefully you end up with a better designed routine, and you get free comments to boot as they now explain what the code is doing. When I first read Code Complete as an impressionable teenager I tried it out and liked it, but I have since had a change of heart on this issue and other Code Complete wisdom. I rarely comment inside methods anymore.

derefr 18y ago
> You then start 'filling out' the code to do what you 'designed' via the comments. Another approach is to just drop the comment markers entirely, massage the pseudocode until it's valid syntax, and then write a DSL that does the right thing upon its execution. That way, all you ever really have is comments.

gaius 18y ago

This is called 'literate programming'.

etal 18y ago

It is a good approach. The PLT Scheme textbook How to Design Programs walks you through a process for writing new code that more or less goes like that: 1. Write a comment describing the problem. 2. Write comments describing the form of all the data structures involved in the problem, and turn those comments into data definitions. 3. Then write a comment describing the input and output of a function, write the function header, use the form of the data structures defined above to sketch a function body with comments and a few bits of code; repeat for each operation. 4. Finally, fill in the gaps -- at that point it's almost obvious how each function should be written.