Pseudocode is one of those things I haven’t touched since college. I tend to think like you do in that sense - I want my code to be as self explanatory as possible.
On top of that, I’m much more prone (to my demise) to sit down and start writing code than I am to sit down and think through the problem/solution to the point of writing pseudocode. And even when I do, my pseudocode looks like nothing more than modified regular code (calls to functions with parentheses, etc.)
I use pseudocode only when working on an algorithm/business logic that is not strait forward. Good for telling my team leader this is how I will do it.
Pseudocode is something we all had to learn in computer science… and then quickly discarded as impractical.
It’s excess overhead left over from the days when debugging was extremely difficult. When you only had limited time on the mainframe it made sense to try to get everything perfect the first time. Now it makes sense to try to get pieces work at a time and grow the product in iterations.
Trying to code everything up front with pseudocode only works if you know everything you are going to do before you write actual code. Usually what happens is you write the code and then change your design as the picture becomes more clear.
I’m with you Jeff, code is usually clearer and quicker to write for these kinds of purposes anyway.
BUT, I have had cases where very difficult problems were easier to solve in pseudocode-- because jumping straight to code made me feel like I was really trying to write the final code rather than think through the issue. This is rare though…
Well, I was never a fan of Pseudo code until today. This is a really interesting way to do more stuff in less time. I guess i should go on an grab a copy of this book!
It’s good for a particular kind of function: one that’s neither trivial, nor really hard. If it’s trivial, it’s a waste of time. If its actually hard, then you need to actually design it.
But if you find yourself starting a function that needs a little bit of thought, PPP is a quick way of, essentially, writing an outline. An outline (or pseudocode) is very good at focusing the brain on the parts of the problem you don’t actually know (yet) how to solve. No painting yourself into corners.
And as for comments first or last, I find writing comments after code to be boring drudge work, while writing them first is not; perhaps you need to think of each comment as prefaced with And now, Ladies and Gentlemen, I shall… and enjoy the imaginary applause. YMMV.
I see one other benefit to PPP: someone with some technical expertise can write pseudocode, without needing to know what language the code will actually be written in. This can be useful when writing a technical specification without knowing which language will be used, or reusing the same technical specification if during a project it is deemed necessary to use a different language - even for part of the project.
That being said, I am not a fan of PPP. I think like you Jeff - in code. It’s probably considered really bad practice, but I actually prefer to simply write code WITHOUT a technical specification. I can work this way, if required, but, in all my experience with technical specifications, there are so many variables (for lack of a better term) once you actually sit down and start writing code. Even small pieces of code end up not working according the specification when attempted - i.e. someone writes pseudocode for a validation script, and then when it’s handed off to the developer, the developer realizes that the validation logic has already been written in an existing class, and that can be used. Stop what you’re doing! Gotta go back and edit the spec! I feel it just slows down the whole process - and why?..so you can have this pretty document that describes the code??? Just look at the code!!!
Sorry, I get worked about this stuff…
Great article! I’ve given it a try before, and while the idea seems really ingenious, I just found that the pseduo code based comments seemed really obvious.
I feel like having a good use case and proper domain analysis in combination with small function sizes, refactoring (when needed), and verbose variable/method names goes a long way in making code easy to follow.
I think if comments read too much like the code then it’s a little pointless having them there.
Of course, everyone does it a little differently. 
I use pseudocode as I need it: to help map out complex processes and for the problems that stump me. But, if I take the overall tone of Code Complete correctly, pseudocode isn’t something that absolutely has to be done all the time for every line of code because it can be impractical in the long run. I’ll sometimes even mix pseudocode with actual code when it comes to functions that I commonly use as a sort of shorthand while brainstorming. Everyone has their own style and Code Complete, I think, allows for a wide variety and using pseudocode is no different.
It seems silly to have these two lines together
//look up error message
LookupErrorMessage(…)
Any programmer would be able to realize that is the purpose of the line.
However, I have found that writing comments can help a programmer in the future (including myself) figure out what is going on. Often I will have a comment that says what a block of code (not just a single line) is doing. So, if it took 6 lines of code to look up the error message, then that one line comment would allow someone to essentially skim over the next 6 lines of code (unless if they are looking for a bug that exists in that block).
I think that as long as comments are meaningful and kept up to date, they do more good than harm, but there is nothing worse than inaccurate or out of date comments.
I haved used it with success only when writing very dense code. It makes no sense for most code, but sometimes the algorithm stresses your ability to keep all the relevant information on your head at the same time.
For example when writing low-level concurrent code or code that deals with transaction boundaries. I’ve also used it for code that, while not involving concurrency, had many special cases that have to be considered (i.e. implementing type inference in a compiler).
Psuedocode is only important in that it forces you to think about the high-level design. I have seen many programmers fall into the trap of going directly to the low-level and never understanding the basic purpose of what they are building. It does not have to be psuedocode, but IMO, making some kind of high-level design document is a requirement in business software development. It also helps people keep grounded, and to not stray too far from the original design. I’ve seen a lot of cases where programmers didn’t take the time to understand a possible solution for their problem, just started hacking away at it, and ended up with bad code that doesn’t really meet the need. I see this a lot in SQL, with both the database design, and the queries and stored procedures, and the database is the foundation of your software - taking a little extra time to get it right can’t possibly be a bad thing.
I started learning a little bit about programming just for fun, and I found myself actually using this thing you’re calling pseudocode. I’ve never taken a computer science class or anything.
I found it useful for coming up with ideas on how to write a program before I knew how to do half the things I wanted to do. I wanted to make a bunch of stuff, but I hadn’t yet learned how to do everything, so pseudocode was the only way I could write down what I was thinking.
One thing to keep in mind is that modern languages tend to be pretty powerful. Someone made a sarcastic comment above about Python being both, but really, lots of languages like the C# code I write looks that way.
Think about whatever coding task you’re currently working on, then imagine what it would take to implement the same thing in C. Pseudocode expansion would make a lot more sense.
Strangely I had almost exactly this situation today at work. I was working on an algorithm to solve a problem I had and I thought ‘I’ll write this is pseudo-code’ so fired up a text editor and started typing. Pretty soon though I realised I was actually writting (Delphi) code, just with a slightly freer syntax to allow me to get thoughts to screen as quickly as possible. The translation to real code will be, obviously, trivial - just making sure I’ve got variable names right etc.
I use pseudocode. But, I think you are mistaken, in that pseudocode needs to be very muck like english. Pseudocode can and often make more sense to be a simplified mix of english and code that states what you are going to accomplish and how. Now this is not needed in all functions, that would be over kill. Rather for higher level functions, that are going to be call on other functions to do the work. I use pseudocode to outline what need to be done and what those functions are. Write the code, and then write the other functions. Though I use vim and tend to do top-down development. I can see PPP being more useful in this style, then bottom-up as most IDE force you to do (http://charlespetzold.com/etc/DoesVisualStudioRotTheMind.html).
I knew exactly why you didn’t like PPP the minute I starting reading this blog entry. Why? Because I disliked these ideas for the exact same reasons and I felt the same way when I read Code Complete.
Sadly when I refer back to the book now it seems very common sense. Although I have to say, there are many developers who just don’t get it. Look around at your current code base and you will see what I mean.
I think in code when I’m writing code. When I comment something it is at the method/class/package level in the doc standard for the given language. Notice I said when I comment. Yes, I’m sick of working on projects with individuals who argue that they don’t have time for comments. That said, other than complex algorithms or strange code barnacles I don’t believe comments internal to methods are helpful.
I use a combination method. Write the parts in pseudocode that are complicated as code, and write the parts in code that are easiest as code.
In the above example, I’d write pretty much none of that as pseudocode, since the code is just as simple and legible. But all the potentially confusing parts extracted as separate methods. Namely:
LookupErrorMessage( errorToReport )
CurrentProcessingMethod()
DisplayInteractiveMessage( errorMessage.Text() )
If those were inline rather than separate methods, then you’d want comments to explain them. Or if the if statement had complicated logic.
Now, perhaps you have a programming style of taking anything that’s remotely complicated and putting it into its own method or variable. In that case, pseudocode isn’t called for, so long as the methods and variables are named appropriately.
I suppose a similar reasoning is behind the literate programming: don’t bother to write pseudocode when you can write actual and exhaustive documentation around your code and get the code extracted automatically with a couple of tools.
It would be nice to read your take on literate programming if you ever give it a try.
I’m a junior developer coming from a Sixth Form background in Pascal and a University background in Java, in a professional .NET environment.
I use PPP to have the general flow of a method from start to finish before writing the code. This is useful as a Junior as it helped with a brief review with other developers to make sure I was on the right track for my first bits of work.
I want my code as readable as possible, so having green (depending on the IDE colours) signposts throughout a method shows what it is doing, not how it is doing it. This makes the method readable at a glance.
I’ll see how I go when I need to code more under quicker time scales; Psuedocode could be training wheels that come off when C# becomes as readable as English to me and whether these comments become redundant clutter.