Psuedo Code

[dpminusa]

Why not compromise. Create meaningful names for all the code elements so the code reads a bit like pseudo code anyway. Document the trickier algorithms in block comments. Use snippet shortcuts to help with the block comments like C# has. To make more complete doc use a generator(s) that reads your code and snippet formats. This does not seem too excessive to me. No doc at all seems extreme to me. Even if you are a gifted programmer you will forget things, waste times, and piss yourself off. Why create the aggravation?

"Courtesy is the product of a mature, disciplined mind ... ridicule is lack of the same - DPM"

[TRK3]

I do that to, but I usually then cut and paste the whole thing into a block comment in the code. I like to keep the notes around so I can refer back to them if I need to, and if I don't put them in the code as a comment, I'll never find them again.

[wizardzz]

dpminusa wrote:

Create meaningful names for all the code elements so the code reads a bit like pseudo code anyway. Document the trickier algorithms in block comments. Use snippet shortcuts to help with the block comments like C# has. To make more complete doc use a generator(s) that reads your code and snippet formats.

I definitely agree with this. I have always documented my code well as I write, but I use psuedo code as a logic holder for my actual code. For example, when trying to plan I will write something like

//get auto liquidity flag from database

instead of writing this code and the corresponding stored procedure, etc.

            \_auto = (bool)ExecuteScalar(SP\_GET\_AUTO\_LIQUIDITY,
                                            new SqlParameter\[\]
                                                {
                                                    new SqlParameter("@account\_id", account\_id)
                                                });

Just to keep my logic concise until I am confident in how I want to do it, then I code. I feel like sometimes if I don't do this, I may get too far along in my code before finding an underlying issue I would have seen sooner in psuedo code.

"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson

[TRK3]

Paper and pen are a lot faster. But just scan the paper and store the image in the documentation folder. Don't waste your time trying to convert it to Visio. Visio is a tool for management types that don't have anything better to do with their time but draw ugly pictures.

[Albert Holguin]

:laugh:

[TRK3]

Because, the reader may have no idea what it means to "Process" the Member ID. I certainly wouldn't have a clue based on that function name. What does it mean?

[Slacker007]

TRK3 wrote:

Because, the reader may have no idea what it means to "Process" the Member ID.
 
I certainly wouldn't have a clue based on that function name. What does it mean?

Read the code. If you don't understand it the first time, then read it again. [edit] Also, I have never worked on a project or a code file without doing some basic leg work to know what it does in the first place; either by someone telling me or finding out myself. By doing this elementary leg work I would have found out what a member id was. Hence the function name: ProcessMemberID...oh, this is where I process the member id that I just learned about through my elementary leg work. No obligatory, worthless, useless, comment is needed. ;)

----------------------------- Just along for the ride. -----------------------------

[TRK3]

Yeah, but sometimes the code doesn't actually do what the original programmer intended. Then if you have a comment at the top explaining what the programmer intended and you read the code and see that it doesn't do that, you have a pretty good idea that might be the cause of the problem. On the other hand if there are no comments and you read the code and see something that looks strange to you, you then have to go and examine the whole system to see if the programmer was being really clever or really stupid -- you sometimes can't tell the difference if there is no comments.

[RomTibi]

I am a ONE MAN SHOW, coding and documenting the product, of course, testing...

36. When you surround an army, leave an outlet free. ... Do not press a desperate foe too hard. SUN-TZU - Art of War

[James Lonero]

Reminds me of the old days, when you had to schedule computer time at the terminal. Back then, you would write your program or algorithm in code on paper, then when it was your turn to use the computer, you could type it in, save it, and compile it.

[James Lonero]

Many times when I have a complex procedure to code, I will make a bulleted or numbered list of what must be done, then fill in below each point, the code to achieve the action. For example:

int TestExample::GetCountOfScansReadIn(void)
{
//1. Initialize data structures
//2. ...
//:
//4. Release resources and memory
//5. Return result.
}

Then fill it in (C++ example):

int TestExample::GetCountOfScansReadIn(void)
{
//1. Initialize data structures
m_pScanBoundaries = new ScanBoundrySetting[m_nNumScanIndexes + 1];
m_pScanBoundaries[0].m_llScanOffset = 0;
SCANINDEX* scanIndexes = m_pScanHeader->GetScanIndexes(m_nNumScanIndexes);

//2. Get the needed data
for (int i = 0; i <= m_nNumScanIndexes; i++)
{
:
}

//3. Release memory
delete [] scanIndexes;

//4. Return result
return m_nNumScanIndexes;
}

[Marbry Hardin]

I usually write an empty shell, and start inserting comments as placeholders for functional blocks within that. It gives me a good target to throw code at when I come back through. I've seen far too much code that was horribly written and near impossible to update and maintain. I try not to leave it like that, at least commenting on anything worthwhile I dicover while going through it.

[Joan M]

TRK3 wrote:

But just scan the paper and store the image in the documentation folder.
 
Don't waste your time trying to convert it to Visio

I love the new quotes! Well, apart from that... I prefer to go through visio as I can modify the document in a future and it occupies less space than a decent picture. Could it be that I'm a little bit pointy haired? :~

[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.

[Joan M]

Way oooold times those ones James... ;)

[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.

[hoernchenmeister]

That reminds me of a comment I came across lately: // this function is a quite complex one // todo: write detailed documentation for it That was basically the only documentation in an older, 1500 lines class ;)

[Stefan_Lang]

Depending on the situation I write psuedocode both before and after the coding: I often program algebraical functions or complicated algorithms. When I do, I first derive the best way to evaluate the various formulae that I need, then type that in as documentation, then translate it into code. This way I make sure that anyone coming after me has a chance to see what kind of computation I was trying to implement, and if either my formulae went wrong, or the translation. In effect, my pseudo code are mathematical equations, with a bit of extra text to explain what principles I used to arrive at them. On other occasions, when I implement some intricate framework magic, I put most of the documentation into the class header and explain what, exactly, this class is meant to accomplish (and sometimes what not!). In a well designed and documented class it shouldn't be neccessary to put a lot of documentation inside the functions. Therefore, in these cases, I ususally just explain the parameter and return values, and sometimes the assumed pre- and post-requisites if they're not obvious. If i put in pseudo code in these classes it will usually only be after the fact, i. e. when I realize the code has become so complex, it's hard to grasp without some explanations. I also do some pseudocoding-after-the-fact when I'm forced to analyze some obscure code and after some effort manage to divine it's intent. Since I spend half of my time analyzing foreign (and poorly documented) code there's quite a lot documentation coming from that venue.

[wizardzz]

I had recently inherited a project that performs calculations on currency rates. Some of the algo's were about 80 lines long and nothing in the entire project was documented. The guy who wrote it has left the country, too.

"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson

[Stefan_Lang]

wizardzz wrote:

The guy who wrote it has left the country, too.

Wise decision! :)

[TRK3]

Joan Murt wrote:

Could it be that I'm a little bit pointy haired? :~

Wear a hat -- it will hide the hair. :doh:

[johannesnestler]

That's nothing - I worked on a real big software - 35 million lines of c++ code. The component I had to work on was 1 Millon lines... We were not allowed to write any comments in the code because the build machine wouldn't build the software over night if it had to parse the comments... THAT was hard to maintain!