Psuedo Code
-
I used to do that a lot, but not any more. OOP guidelines are to favour shorter methods that do just one job, so really there's not much need for pseudocode comments of something that small. Hopefully, the higher-level methods call lower-level methods with good enough names that the intention is clear. Of course, where algorithms are important, I may still pseudocode, but that's typically on a scrap of paper by the side of the PC. The only place I comment nowadays is generally where: (i) The code does something non-obvious, such as a workaround for a bug, or... (ii) The code exposes an API callable from other modules, possibly written by other dev's - I don't expect them to root through my code to determine how to use it. Again, well chosen method and parameter names can help a lot here.
Same here:thumbsup:
There is only one Ashley Judd and Salma Hayek is her prophet! Advertise here – minimum three posts per day are guaranteed.
-
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 did in the early days. No more. My feeling now is, if you're going to put that level of effort in up front, then just write some bloody tests and you have an executable specification of what the code does. The point of that comment first approach was never the comments that were left in the code, it was the advanced planning for the next bit of coding. Indeed the kind of comments you write before you write code are exactly the kind of comments that I hate to see in Code. ' Get the Log Filename and Path logFileName = Config.GetLogFilenameAndPath(); ' Open the Log File logFile.Open(logFileName); ' Write the event details logFile.Write("Bored out of my tree"); ' Close the logFile logFile.Close(); etc, etc. You might not go into that level of detail, but the point remains, comments written before code then to focus on what the code does. If the code itself is written properly those are completely unnecessary comments. -Richard
Hit any user to continue.
-
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 do this occasionally. I write the algorithm in fairly plain English text in comments. The code gets inserted betwixt and between the comments as necessary.
Software Zen:
delete this; -
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. -----------------------------
Same here. I have notebooks dating back 10 years. I have the luxury of being the only coder here for the last 10 years. I only comment code sections where bugs were fixed...unless it was something really stupid, then I destroy any evidence of it!
"Go forth into the source" - Neal Morse
-
There is not a single line of documentation in the thousands of lines of code in our production software. I got here 6 months ago, so it is out of my control.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
wizardzz wrote:
There is not a single line of documentation in the thousands of lines of code in our production software. I got here 6 months ago, so it is out of my control.
It was like they were planning on making it hard to maintain...
See if you can crack this: b749f6c269a746243debc6488046e33f
So far, no one seems to have cracked this!The unofficial awesome history of Code Project's Bob! "People demand freedom of speech to make up for the freedom of thought which they avoid."
-
wizardzz wrote:
There is not a single line of documentation in the thousands of lines of code in our production software. I got here 6 months ago, so it is out of my control.
It was like they were planning on making it hard to maintain...
See if you can crack this: b749f6c269a746243debc6488046e33f
So far, no one seems to have cracked this!The unofficial awesome history of Code Project's Bob! "People demand freedom of speech to make up for the freedom of thought which they avoid."
-
The job ain't done until the paperwork is finished...
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
Hear, hear.
Daniel Vaughan Twitter | Blog | Microsoft MVP | Projects: Calcium SDK, Clog | LinkedIn
-
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:
