Psuedo Code
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
My comments don't usually take the form of pseudo code. The real code is usually more than enough. Who made the change, when they did it, and why are usually about it. For new function or module definitions, sometimes, in addition to basic parameter and function descriptions where needed, I put in use case examples; so, people will know how best to call the thing. The examples are usually excerpts copied from real code that calls the new functionality. After all, why fake the code in a comment, when you can show them the real thing?
-
My comments don't usually take the form of pseudo code. The real code is usually more than enough. Who made the change, when they did it, and why are usually about it. For new function or module definitions, sometimes, in addition to basic parameter and function descriptions where needed, I put in use case examples; so, people will know how best to call the thing. The examples are usually excerpts copied from real code that calls the new functionality. After all, why fake the code in a comment, when you can show them the real thing?
Well, for me, it's usually to hash out a big picture idea first. I don't do this instead of comments. Sometimes it's easier for me to analyze my logic or algorithm before taking the time to write the actual code.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
When I first started out, I did use pseudo code (done outside of the source). It didn't take long to realize that it about doubled the time that I worked on a project. Since then, I have applied other, more visual tools to break down complicated processes, but mostly, I use Freemind, a mind mapper, to document other people's code and to create basic structures for new code. A mind mapper is a wonderful tool that is completely visual and allows linking to other documents, the Web, and even other applications, if need be. For a particularly knotty problem, pseudo code might play a part in evolving a solution. Otherwise, I don't see much use for it in today's code environments.
The avoidance of taxes is the only intellectual pursuit that still carries any reward. John Maynard Keynes
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
I think by writing. My writing becomes the comments. I comment everything. I worked at a place where they didn't do documentation. In six months, I wrote more documentation than the whole team did in the 10 previous years. You can always lead by example if you feel comments are important.
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
I find it (but I wouldn't call what I do psuedo code necessarily) helpful when you are needing to write a section of code that you may write over the course of a week, like, when you don't get to code 100% of the time in a days work. Or during the time of the day you have you start, stop, start, stop, due to meetings and other interruptions. So yeah, it helps with that and then to sort of pick up where you left off and to see what your grand scheme of things was on days 2-n when you get back to it.
-
I do it... it makes me think of things more generally rather than getting caught up in details off the back... it makes the actual code writing go a lot faster later on since I don't have to rethink "what's next?".
-
I only really do this in two circumstances. One is if I'm tired and nearing the end of the day and I can see the next hour or so of coding in front of me but just don't have the time to do it. I'll write out the remaining steps in the logic in the form of comments, so the next morning I can pick up the mindset I was in when I finished the previous day. The other circumstance is when I am assigning a task to a junior coder and want to give them a starting point if I don't feel they would have come up with the same logic I did. Especially if they are new to a project, I will often write the method stubs and then the 5 or 6 steps the code needs to take to accomplish the task. I will leave it up to them to actually translate it into the equivalent code. On the topic of comments themselves, I still do write a lot of them. Comments still have a place in defining the interaction of your objects and methods with the larger scope of the project. I never accept comments such as:
// Save the changes
context.SaveChanges();In fact I rip those out on sight. Instead, comments should not address "what" but "why", and discuss the component's part in the overall scheme of things. For example, the point of the following object is not immediately recognizable (took this from a recent project):
public class ColumnContext
{
public int Identifier { get; set; }
public int Date { get; set; }
public int Value { get; set; }
public int Weight { get; set; }
}But the same thing with comments becomes:
// The column headers in the data worksheet are identified by named ranges ("colHeaderValue", etc.) This allows the user
// insert columns, move them around, etc., and we can still identify where the data is. The ColumnContext class stores
// the result of our looking around to see where the data is actually located and acts as a map between the logical
// columns and their physical column numbers in the worksheet.
public class ColumnContext
{
public int Identifier { get; set; }
public int Date { get; set; }
public int Value { get; set; }
public int Weight { get; set; }
}Granted, you could have just Find Usages'd and looked around the code at what this object is being used for... but then you could say the same thing for any commented code. Another example, this time some annotations about the method's usage in the overall scheme of things:
// Take a filename for an uploaded KPI data worksheet and return a POCO contain
Just a comment. . .have you tried or if you have, what do you think of, the nifty autogenerated comments that include parameters and return value that you get when you type 3 forward slashes above a method?? . . .I think this is just a Visual Studio thing AFAIK.
-
Just a comment. . .have you tried or if you have, what do you think of, the nifty autogenerated comments that include parameters and return value that you get when you type 3 forward slashes above a method?? . . .I think this is just a Visual Studio thing AFAIK.
I don't find them nifty at all. They uglify the code needlessly. When I see them used I almost always see things like <return>Returns a bool</return> and other useless things like that which just take up space.
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
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"
-
I used to... Nowadays, if I have to work out a complicated algorithm, I'll pop open a notepad and outline the general flow (Not even pseudo-code)... But that rarely makes it into the code comments. I do those after I get it working.
Proud to have finally moved to the A-Ark. Which one are you in?
Author of the Guardians Saga (Sci-Fi/Fantasy novels) -
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"
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
-
I do that in paper before putting myself in front of the computer... Even there are tools like Visio and others I'm faster doing it by hand... Then at the end and depending on the complexity I make the final flowchart in visio and store that in the documentation folder or if it is easier I use that approach you are describing. Whichever is the choice it is always a must to put lots of comments in the code.
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
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.
-
Yes yes.:thumbsup: As Dave Letterman used to say "Once again, Paul, you've crystallized my thoughts most eloquently"
:laugh:
-
wizardzz wrote:
How many of you hash out the logic of what you are about to write in a comment, then code it?
I actually write the basic logic on paper and mess with it there and then I code it. I can see the events and logic flow in my mind and I know how it will behave, to a point, then code it and inevitably debug it. I once read that if you have to describe in detail what your a function or other code does in comments then you have failed your job as a coder. Your code should be clear as to what it does and how it works in a general level. Now, this was a Microsoft developer that said this so take it for what it's worth. :) I see his point though. If you have a function
ProcessMemberIDwhy do you need a comment that says: This function processes member id's. Pretty silly actually.----------------------------- Just along for the ride. -----------------------------
-
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?
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 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. -----------------------------
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.
-
It's called "documentation", real programmer don't do it.
Its the man, not the machine - Chuck Yeager If at first you don't succeed... get a better publicist
-
I do that in paper before putting myself in front of the computer... Even there are tools like Visio and others I'm faster doing it by hand... Then at the end and depending on the complexity I make the final flowchart in visio and store that in the documentation folder or if it is easier I use that approach you are describing. Whichever is the choice it is always a must to put lots of comments in the code.
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
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.
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
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;
} -
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
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.