what is with the double posting? @jeff!!!
Though, of course, it does not correspond to the pseudo code, which says append A to B, not B to A. Thatās a bug, though. 
I often do this, though the pseudocode/comments are only for me to remember what it is that Iām trying to accomplish along the way. It takes no time at all to put down some sentences about what Iām trying to accomplish in English and then flesh out the code afterward.
Sometimes the pseudocode ends up as a comment but often it is deleted as it is clear what the code does.
I use it mostly as a checklist of what Iām hoping to accomplish in the function. The details of how Iām going to do it arenāt essential initially when Iām thinking through the design.
I do this if Iām writing a function complicated enough that I canāt hold every step in my head simultaneously. First just write out each step in a way simple enough to fit into a one-line comment, then fill in the space below each comment with the code for that step.
If you end up with only one line of self-explanatory code for a comment then I can always just delete the comment when Iām done. If the code is somewhat more complicated I leave it in as a useful summary of what that block does.
If a block gets really long/complicated or shows up more than once you extract it out into its own function.
If you debug by reading comments, you are doing it right. Iām tired of finding bugs where what the code DOES and what the comment says itās SUPPOSED to do donāt match. And, of course, no one can find it, because they have read the comment, so they misread the code into doing what it was supposed to.
Thatās why I never read the comments when trying to understand what a code does.
Sure, document what the code should accomplish, and why. But never get into the how, because the only how that matters is
Tiltonās law, learn the damn language.
http://smuglispweeny.blogspot.com/2008/07/now-batting-dave-roberts-why-is-mariano.html
I remember I was once reverse-engineering a file format, and wrote some code to test things (read specific information off the file), apart from a textual spec.
The other guy who was working on the project saw what I had committed to SVN and said
I really hope you understand what all that pseudocode means
oh wait, itās python
Indeed it was.
I use it sparingly, usually in relation to implementing an image processing or numerical operation.
Iāll also admit that I usually delete my original pseudocode comments and write the algorithm out in the method comment
I often code this way, except I donāt call it pseudo code, I call it English (insert spoken language of choice here). When I go to write a routine and if I have much of the reasoning already worked out, Iāll quickly commit those thoughts as a series of comments. Sure, Iāve been writing code for a long time but I still canāt write code as fast as English.
Sometimes I start writing code first if the the code is quite straight forward but thereās always times where I change my mind about the approach or I realize an additional bit of required logic. In this case, Iāll quickly jot down some more comments so that the new and current lines of thought arenāt lost.
It is true that the resulting comments mirror what is often unambiguous code. The purists generally donāt like this but I firmly believe that code alone only tells you what it does, not what it is supposed to do. So I write what it is supposed to do first.
Cucumber lets me write pseudo code which is used for testing. So I suppose writing pseudo code is part of what I do
Iām like most others here. Iāll write pseudocode if I have trouble wrapping my brain around itā¦ but then I put the pseudocode in the ide, write the function below it, translating each piece of pseudocode into real code, and then I delete the pseudocode.
Agreed. Pseudo-code is very impractical. All those layers of documentation may make sense for an ISO, but for your average small to mid-sized engineering house, it generates too much overhead.
Personally, I like comments, but only to a point. I generally comment modules (i.e. file headers), functions, and branch statements. Other than that, I agree with Jeff; code should be as human-readable as possible.
As an afterthought, I do write pseudo-code when Iām doing low-level debugging of someone elseās code, so I guess it has a place, albeit limited.
I donāt like pseudocode either. It was extremely useful when I was a beginner, but afterwards it did me no good. It simply wastes time for me nowadays.
And I really donāt like having comments that word the code below them.
Comments that can be made wrong with minor code cleanup suck. Design documents that have to be changed frequently suck. Trying to reason about formal subjects using only informal notation sucks. Writing the same thing in two very similar ways sucks.
(Yeah, I know, you want to know what I really feel.)
Yes, Iām prejudiced. I went for several years with systems analysts thinking that a buggy program written in some sort of pseudocode (actually, they used bastardized decision tables) was an adequate spec for a real program that was actually supposed to work. (Look, guys, Iām the expert in converting specs into programs. Tell me what the programās really supposed to do and Iāll make it happen.) I was, of course, responsible for any bugs put into the low-level stuff by the analysts, and not given enough context to know they were bugs.
Iāve seen vast arrays of entirely useless comments, which were no more clear, and gave no different information, than the code. Heck, I used to do that sometimes, before I knew better.
Iāve seen comments that described what the code was doing, and been specifically warned away from them, as they were misleading.
Pseudo-code has its uses. Itās good for algorithms books, for example, since it ages well. (Iāve got a book with routines written in Fortran - excuse me, FORTRAN - and APL. Pseudo-code would be nice.) Itās useful as scaffolding in working out a routine, WHEN DONE BY THE GUY WHOāS DOING THE PROGRAMMING.
But donāt use it for design reviews. Itās low-level and untestable, and can be ambiguous. Donāt use it for comments. Thatās something Iām just going to have to ignore when maintaining the code, and besides it gives the code the look of commented code, so nobody will put in the actually useful comments. Donāt use it for specifications. Itās on the exact wrong level of abstraction.
I have been known to use the pseudocode approach. It often works great for algorithms, but not much else :(.
Pseudocode has always just been a language-agnostic way of conveying algorithms and data structures to me. I canāt imagine actually writing it out unless I was trying to explain something to somebody who didnāt code or coded in another language.
Personally, I am not really a fan of pseudocode ā it is like a programming language with ill-defined syntax and semantics. If in doubt, you have to guess what the author really meant.
Instead, I prefer code written clearly, with real variable and function names (not grmblPsft()-style). The example youāve given illustrates this quite well: the pseudocode comments do not contain significantly more information than the C version. Of course, you could have written it like this:
st err_stat = fail_st;
Msg err_msg = err_lk( err );
if ( err_msg.vld() ) {
pm err_pm = curr_pm();
if ( err_pm == pm_i ) {
i_msg( err_msg.str() );
err_st = succ_st;
}
In that case, extensive comments and pseudocode would have been useful lest we have to guess what each variable, type, and function means. Thatās why I like the rationale behind Adaās somewhat more complicated (as opposed to C) syntax: code is written once, but read many times; so it should be easy to read, not necessarily easy to write.
That said, I am a sysadmin, not a full-time developer. I write the occasional small utility, and I dig through other peopleās code hunting for bugs; but requirements may be different when working on large projects.
Sure, this is stupid:
// lookup the user id
id = lookupUserId();
But thatās a straw man.
Whatās meant by PPP is this:
// update the widget on all the ones that matter
for (iterator i=things.begin();i != things.end();++i) {
if (i-isCurrent() i-isImportant() ! skipList.has_key(*i)) {
i-updateWidget();
}
}
When doing the pseudocode, you can skip over the details about EXACTLY what ones that matter means. As long as you are confident that it CAN be determined which ones matter, then you can go on to worry about whether widgets should be updated before or after the foobars are pruned.
Once in a while you discover that you canāt update widgets before OR after foobars are pruned. At that point, you are only 60 seconds into writing the function and you need to look to see if there is a better solution. PPP has improved your efficiency.
Of course, if you never write code that has subtle issues like this, you are either working in a very simple domain, or you are much smarter than me.
I find it easier to think about code in code.
But you shouldnāt be thinking about code. You should think about logic at that point.
Do you write pseudocode before writing code?
Both. At onceā¦ Python \o/
+1