Fog Creek Software
Discussion Board

Writting all the comments then writting the code

When I program, I first write all the comments,
read the comments, make sure that the way the comments are structures is a perfect fit for what I'm tryinng to achieve then I write the code.

Do you think it's an effective way of working ?

If not, please explain me why

Sunday, August 22, 2004

The term you are looking for is pseudocode:

and, like every other technique on the planet, if it is what gets you to write good code that you can maintain and solves the domain problem with the least amount of bugs, then you are doing just fine. Personally, I like an approach similar to it, but am starting to really look into Test-Driven Development, mainly because it is a fascinating approach to structuring things.

Sunday, August 22, 2004

Sounds to me like you're over-commenting. If you're commenting on the whole structure of your code and saying "do this, then do this, then do it again if it's yellow," then you're writing a specification, not commenting.

Thom Lawrence
Sunday, August 22, 2004

I did learn that trick after reading one of Steve Mc Connell Book

He call that PDL :

>> DDJ
DDJ : How is PDL different from pseudo-code?

SM: I use the term PDL pretty loosely in "Code Complete." There are people who would say that there needs to be a stricter use of that term, but the way I use it PDL is about the same as pseudo-code or about the same as structured English.

I do agree that at a low level this is taking a top down approach. Programmers who use the technique I describe --writing out what you want the routine to do in English, converting those statements to comments, and then filling out the code below each comment-- find that it has a lot of benefits. It produces, it makes the coding go very quickly, it makes the coding relatively free from errors, and it leaves comments in your code when you're done that you don't have to go back and put comments in later. They're already in there just by virtue of the way you went about writing the code in the first place.

So I think there are a lot of benefits. It's a good example of a technique that's actually very simple and somewhat deceptively so, in that it produces some really major benefits, considering what a simple practice it is.

<< Cut

Sunday, August 22, 2004

Hm, I suppose I've done that. I just got rid of the original comments afterwards. :)

Thom Lawrence
Sunday, August 22, 2004

I do that sometimes, but I always delete the comments once I've written the code. Either the code and the comments say the same thing or one of them is wrong; either way it's duplication.

If you cant understand the intention of the code without the comments then 95% of the time you just need to rewrite the code until you can and 5% of the time you need a nice block comment that explains the intent rather than the actual process.


Len Holgate (
Sunday, August 22, 2004

Sounds like Donald Knuth's Literate Programming to me.
Background information and an excellent tool at

I think it's a great concept provided it's not taken to excess

Sunday, August 22, 2004

I've done that and deleted the comments afterwords as well. Upon reflection, I think I am going to stop deleteing the comments.  I am going to spend a few minutes putting them in sync.  Often, I write my first idea for an algorithm in comments. Then write the algorithm in code, then re-code, then test, then re-code, then delete the comment.  *sigh* 

Sunday, August 22, 2004

Sounds OK to me - at a subroutine level. It helps think through the logic of a subroutine but won't help much with ensuring that the software as a whole meets requirements.

On deleting comments: there really isn't much point in deleting comments in today's world of software development:
* If you are using a compiled language the presence of comments has no effect on the compiled code.
* Disk space is cheap, no need to keep files small
* Modern IDEs often allow you to collapse comment blocks when they are getting in the way.
* Controversially, IMHO you can never have too many comments.

Herr Herr
Monday, August 23, 2004


I do the same thing roughly. But I write those comments in the first place after I've thought over the problem for a couple of days over.

But I hate too much of commenting, so after a while when I'm done coding, after a few weeks, I just delete many of those comments.

Sathyaish Chakravarthy
Monday, August 23, 2004

They tried to make me write the whole program in comments in school... that was right about the time that I switched majors to something besides computer science.  That's what I think of pseudo-code that looks the same as regular code.
Monday, August 23, 2004

For a more extensive change, I will write out an initial design document in a stream of consciousness fashion that details the pros and cons of multiple approaches to the problem.

While writing this document, I tend to think about the 3-7 details I want to see at each point within the code.  This forces me to break the code down into logical sub-units early in the process.

(For a simple change, my design process starts here)
Once I have settled upon an approach, I write a text document containing pseudo-code for the trickier parts of the implementation.  Sometimes I will encounter a new wrinkle while writing the pseudo-code which forces me to reeveluate my initial decision on how to approach the problem.

I store all these documents in version control for later consulting as necessary.  95% of the time the code is self-explanatory, and I never use the document again.

I almost never use block comments.  If a block of code needs a comment, I find that it is either unclear in intent or should be broken out into another function with a descriptive name.  If you cannot come up with a name for the new function, then the the block is probably doing too many things at once.

I find test driven development interesting because it promotes writing simple clean API by having you write simple test cases first.  If you cannot write a concise test case then your API is inelegant for the problem being solved.  The tests are to degree just a very useful by-product of the design process.

Monday, August 23, 2004

Writing down your thoughts is a great excercise because it really makes errors more visible. You can also show it to someone else to make them even more visible.

And thinking a LOT about your design is very effective. When I started as an engr I spent maybe 2% of my time on design.  That doubled ever time until I got to about 55%.

Mr.Analogy (Shrinkwrap ISV company owner)
Monday, August 23, 2004

The problem with having lots of comments, especially ones about the process is that sooner or later they will not match up with the code.  This will lead to confusion when you come back to it 6 months later.

It's better to have comments that say your intent as this is less likely to change. 

The only code that should be explained is very tricky stuff and optimisations imo.

Monday, August 23, 2004

I agree with a lot of people here.

*ALWAYS* document your intent.  Nobody (even you, five months later) cares about how you implemented a solution to some particular problem (even if it's a really clever solution).  First and foremost, the actual intent of some chunk of code should be made clear (maybe with some comments of a declarative nature about the problem -- e.g.: sqrt(x) * sqrt(x) = x -- some of these kinds of statements won't be captured correctly by test cases).  The details of your implementation might justify a side-note, but really the first thing that anybody cares about is going to be, "why is this code here at all?"

Monday, August 23, 2004

Almost without exception, the best code I've read (and the best code I've written) has had about a 1.5:1 ratio of comments:code.  That's because no interesting problem has an implementation solution that is so crystal-clear in its operation and intent that it is self-documenting.

I've seen and heard a lot of people say that the best code is so modularized and obvious (whatever that means in the context of a complex problem) that comments are unnecessary.  Bollocks.

Even if all of your functions are 10 lines each maximum, all your method names are descriptive, etc., there has to be a way for a new coder coming into the scene to be able to build up a mental map of how those wonderfully modularized bits fit and work together.  Copious amounts of comments are the only way to provide the kind of ad-hoc mental signposts that allow someone to gradually build up a proper representation of the problem space in their heads.  (I've seen some roundtrip coding tools [TogetherJ, f'rinstance] that keep the comments in a separate tool, but creating such a chasm is (hopefully obvious) folly.)


Chas Emerick

Snowtide Informatics :
PDFTextStream: High Performance PDF Text Extraction Java Library

Chas Emerick
Monday, August 23, 2004

> ... there has to be a way for a new coder coming into the scene to be able to build up a mental map of how those wonderfully modularized bits fit and work together.  Copious amounts of comments are the only way to provide the kind of ad-hoc mental signposts ...

I'm trying pictures, for a change: reverse-engineering class and sequence diagrams.

I'm even changing the code so that the pictures are more readable.

Christopher Wells
Tuesday, August 24, 2004

To clarify my position ...

I  feel that any non-private method should have a descriptive header comment with precise preconditions and postconditions, so I don't think comments are useless.  I think the header comment should only describe intent and not implementation unless the implementation is truly relevant to the client code.

I don't feel segments within a function/method should be commented because if it needs a comment I think it should be made into a function with a descriptive name and a header comment.

The only real use I see for comments within the body of method is to document what the code cannot.  Maybe a work around for a bug in a library.  In those cases, the code cannot be made self-explanatory and it does not belong in the header comment, so a comment within the body may be warranted.  Even so, I would prefer to have a helper method that encapsulates the work around to minimize the complexity of the client code.

I will acknowledge that more complicated algorithms are harder to code in a self-explanatory manner, but I think good decomposition into functions/classes with header comments alleviates the need for most other comments.

Tuesday, August 24, 2004

An 1.5:1 ratio of comments:code sounds excessive to me.

Sure, the best coding style will never completely reveal the intent and the dependencies of the different modules in your program, but the most descriptive comments won't do it either. For that you have to skim through the code, and if you use descriptive class and variable names, i.e. names that are closely related to the problem domain, the dependencies are obvious most of the time, or will be clear to the programmer in a reasonable amount of time.

In my experience the best code (read or written) has always had a minimal amount of comments (a ratio of 0.5:1 or 0.25:1).

Tuesday, August 24, 2004

*  Recent Topics

*  Fog Creek Home