I completely agree with Mike V. The most useful thing for me with new functionality is the whiteboard. It gets you and your co-workers on the same page and saves a lot of time.
The whiteboard is also invaluable for teaching programmers new to the code base how everything works in real time.
re: Steve on May 8, 2009 09:17 AM It is almost impossible for most people to code with pencil and paper when they have a computer on the desk!
I used fullscreen editors for 17 years (starting in 1972) before giving up paper and pencil for onscreen programming. It is much more than the difference for an author moving from longhand to a typewriter.
I often used a 4 sheet of paper working style: Initiation, Termination, Data, and Processing logic. Even if I could have 4 files open at once, my screen size didnāt make it useful to see much of all 4 at once. As I added code to the processing logic that required another variable, I added to the data sheet. If I added a file, I added to the data, initiation, and termination sheets.
re: Pseudocode
In communicating programs, it is useful to document what is not visible in your code, namely what message or action of the peer or network this piece of code is in reaction to. That is the why or when.
It is worthwhile to document a custom protocol in the comments.
In some code I once put a warning: If you do not know what the peer can do and what the communications return codes mean, do not tinker with the next page of code. Years later, in a code review, I saw the same warning and the unchanged code in a totally different program. Of course, I was flattered.
As a warning to future newbie improvers, the following comment makes sense for languages without early termination of logical expressions:
If (k = Int(k)) And (0 k) Then ā do not combine these IFās to avoid using a noninteger subscript
If (pfacts(k) = 0.0) Then
:
:
End If
End If
Iāll usually write pseudocode if Iām sitting down with a piece of paper and/or talking about it with someone. Itās alot easier to jot down a word or two than to start coding while carrying on a conversation. It doesnāt make it into the comments but sure helps go over the design when talking it over with another developer.
This is a very strange argument, pseudocode and self-documenting code go hand in hand and are in no way replacing each other. One tells you clearly what the code SHOULD do, the other tells you clearly what it DOES.
The example given is perhaps a bit extreme, but consider the benefit when you come across this subtle error in the code:
// if doing interactive processing, display the error message
// interactively and declare success
if ( errorProcessingMethod != ProcessingMethod_Interactive ) {
DisplayInteractiveMessage( errorMessage.Text() );
errorMessageStatus = Status_Success;
}
With only the code to look at it might take you ages to spot the error. The difference in the pseduocode and actual code makes it much easier. If this wasnāt technical but instead pseudocode describing an obscure business rule, you might never realise that the code was doing the opposite of what it was supposed to.
So - Pseudocode is awesome, McConnell FTW! 
To me, it kinda seems like when you are learning a new human language: When you are starting out and are not that proficient you actually translate the things you say, write, hear and read back and forth from the foreign language and your own. But when you get proficient in the other language you actually think in that language as you are speaking it or writing it, just like I am doing right now. Not only is this faster, but it allows you to use the language in a better way, taking advantage of the grammatical possibilities it offers.
This is the same with a computer language: When starting out it may be nessecary to think in terms of human language, but as your skill increases you start thinking in code and this is when you really can call yourself a programmer.
Pseudo code feels like itās more for academics (and something you learn at class in university, but actual programmers donāt use it pretty much) and people who canāt code (and often that means the same thing).
I can think when you revert to pseudocode is when you canāt program in the language (or at all).
Fuck all things that arenāt actual programming - everything else sucks, except actual working lines in your application!
Your wikipedia Tang lang is broken - itās missing the starting at the href=.
The thing about code is that you cannot always make it completely clear without comments, which is why programming languages have comments in the first place! I write code with comments like you show from Code Complete, but I write them afterwards. This has helped even myself understand whatās going on months later.
This reminds me of my recent job interview, where I came to the realization I have no idea how to write good pseudocode. They asked me to write something to go through a linked list and check if it is looped or something of that nature, and I started scribbling out some nonsense that looked like I combined 5 programming languages with a new brace syntax and stuck in some English words for good measure.
It seems I can either go to a very abstract level and write almost a paragraph describing the code, go into a very specific level and write the code itself, but trying to find the right level of abstraction in the middle for pseudocode is difficult.
Plus, there is no standard for pseudocode. Everyone writes it a little bit different, which makes using it to show another developer your ideas often more difficult than just showing them the code.
I am often complimented on the readability of my code, and I use very few to no comments. In modern languages they are not necessary. In the way olden days (and I am dating myself here) with single letter vars, you had no choice but to comment. Long procedural blocks also need commenting since you could forget what all the moving parts were doing by line 5000.
Nowadays, if a routine is so convoluted that it needs comments your time is probably better spent fixing the code than writing a comment to explain the mess.
I suppose I occasionally write pseudo-code when Iām sketching out a non-trivial routine. But they are just placeholders. They donāt end up in the final code at all - not even as comments. Just like sketching, those light lines are eased as the picture starts to take form. They are usually replaced by methods with expressive names.
The example from Code Complete is a violation of DRY. The code already says what it does.
I think itās a valuable tool to have in your toolbox, but itās not applicable to everything. I use it when Iām writing a routine thatās finicky, with a lot of details that I need to keep in mind. For example, when I was writing the stack-based implementation of a recursive serialization algorithm, I used PPP to outline the details before starting so I wouldnāt forget any of them.
However, I switched to C# from C++ (mostly C with a C++ compiler) a few years back, and I canāt remember doing it since. It may be that the domain of problems Iām working on require less of that kind of precision, but it also might be due to using a higher level language where I donāt need to concentrate as heavily on managing memory and error codes, leaving me able to maintain the overall algorithm in my mind without the assistance of psuedocode.
Most of the time, no, I donāt. Iām another who codes to keep the code as readable without comments as possible - if that means slightly longer or less efficient, then so be it. Neither are usually anywhere near as critical as maintainability.
Occasionally though, I will do exactly this. As a rule itās too much but there are some odd problems where I find it far simpler to sketch out an idea to help visualise that, and a comment block is a great way to do that.
The other thing that can be worth playing with is doing this at the block level. Particularly with VS.Net Iāll often code merrily away to all sorts of unwritten functions, then write their XML comment blocks before I start coding as notes for where I was heading. Saves me having to worry about all the bottom up funcationality and just code big pictures, in the knowledge that the bottom up blocks are there to be filled in as needed.
I think this reason for pseudocode:
Pseudocode makes changes easier
is not as strong an argument if your coding environment has strong refactoring tools.
Iāve been doing this for a while, and it works well.
I usually donāt keep the Pseudocode after Iāve written the actual code because it rarely actually describes the code I end up writing.
Pseudocode allows me to write out an algorithm that makes huge assumptions, leaves parts out and only makes sense to me, but it allows me to quickly put a process down without having to think about how Iām actually going to do it(i.e. which libraries, classes, API, variable names, function calls, types etc. Iām going to use).
An example would be something like:
get image
get hist
get image
get hist
compare hists
if threshold
which is a function that compares the histograms of two images and does something if the difference is above a certain threshold.But to
anyone that isnāt me it makes no sense.
I donāt use pseudo code per se, but sometimes I write code as if the libraries I am working with worked the way I want. Easy example, go have a look at how you create render context in GL. http://www.nullterminator.net/opengl32.html . What you might really want is something with a bit less nonsense:
glCreateContext(width, height, bitdepth, hasDepthBuffer);
Such a logical function doesnāt exist, but I might code as if it did anyway. If I get over-focussed on bit flags and tokens, I might spend half an hour creating the context, and completely lose focus on my algorithm. Once Iāve got the algorithm coded up or at least roughed in, I can go back and fill in the details, possibly actually writing the utility functions that I wished existed in the first place.
As a computer science instructor and practicing software developer, I find that psuedo-code at the early stages of programming education is almost essential. It just becomes less so, as one gains experience.
The biggest issue is see is that new students are trying to learn both syntax and semantics at the same time (if they are just thrown into a language). Though itās something that becomes intuitively obvious to the experienced programmer, many beginners really tend to confuse the two concepts. Forcing them to write pseudo-code first is just really forcing them to think about the organizational details before tackling the syntax and implementation issues. I always tell my students that learning to write code without learning to properly plan is like tying to learn a song youāve never heard on an instrument youāve never played.
At least at the early stages, pseudo-code seems to be about the best way to plan, and then the code can evolve from that plan. As you gain experience, you learn how to plan in code with greater precisionā¦ Just like as you gain experience with musical instrument, you eventually stop thinking about where you fingers are going and just play the notes.
I find it easier to think about code in code.
I think most programmers get to this point. But for somebody learning how to code, it seems to work reasonably well, and I use it in my intro programming classes. Students donāt think better in code, and learning to express an algorithm on paper, before writing it, is useful. It also allows them to paper-test the algorithm before committing it to code.
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.
This is exactly correct as well. In the example in the post, pseudocode is used as almost a line of pseudocode to one line of code mechanism. That i9s fine in very early stages of learning how to program, but eventually, that is overkill. However, it can remain useful as a higher-level design technique beyond this. 1 line of pseudocde per function call (or inline block of code) can make sense. When done this way, the pseudocode becomes a task list - a high-level skeleton to ensure that you donāt forget something. And if the pseudocode really does end up simply marking a function call, than I am all for removing the comment and making sure that the function call is properly self-commenting.
Long ago and far away, when I was a young, young guy, I sometimes wrote pseudocode. I found it helpful for stepwise refinement, especially in Pascal. I still find it useful for languages like Lua, which is very powerful semantically but is like a syntactic straitjacket, especially when it comes to looping constructs. But I really just treat it as a more powerful form of code than what I actually have available at the moment. No need to put that stuff in a comment. Comments are for what problem the code is intended to solve and why I did it that way.
Do you write pseudocode before writing code?
No. But I think todayās refactoring tools makes Steveās arguments less relevant. (I love Steveās book, myself, but the way: See http://geekswithblogs.net/btudor/archive/2009/04/05/130772.aspx).
You can āstub-outā real code easily in a modern editor, leaving āNot Implemented Yetā blocks for the details. You can add implementation later, restructuring the code as needed.
The skeleton/stub code is good enough to review, and easy enough to extend.
I donāt tend to write much pseudocode myself, and would agree that PPP is overkill for most functions, but I do tend to think in pseudocode ā think about what I want a function to do, then fill in the details with code. If you donāt do this, you are no thinking about ācode in codeā, youāre thinking about function in code ā starting with the how do I do something rather than the why.
But, preferring to code without comments? Talk about technical debt. Iāve spent too much time trying to maintain code written by developers who thought their code was self-explanatory (including my own code). If code could always ātell the storyā bugs would not exist.